Appendix G. Common Compiler Errors

Zig tries to report errors at the point where the program becomes invalid. Many messages are direct: a value has the wrong type, a variable is unused, an error was ignored, or memory rules were violated.

This appendix lists common errors and the usual fix.

G.1 Unused Local Constant

error: unused local constant

Example:

const x = 10;

Zig does not allow unused local declarations.

Use the value:

std.debug.print("{d}\n", .{x});

Or discard it explicitly:

_ = x;

G.2 Unused Function Parameter

error: unused function parameter

Example:

fn f(x: i32) void {}

Discard it explicitly:

fn f(x: i32) void {
    _ = x;
}

G.3 Variable Never Mutated

error: local variable is never mutated

Example:

var x = 10;

Use const instead:

const x = 10;

Zig distinguishes mutable and immutable storage strictly.

G.4 Expected Type, Found Type

error: expected type 'u32', found 'i32'

Example:

const x: u32 = -1;

Or:

const x: u32 = y;

Use an explicit cast when the conversion is valid.

const x: u32 = @intCast(y);

The compiler requires explicit narrowing or signedness conversion.

G.5 Expected Optional Type

error: expected optional type

Example:

const x: i32 = 10;

if (x) |v| {
    use(v);
}

Optional capture works only on optional values.

Correct:

const x: ?i32 = 10;

G.6 Optional Unwrap Failed

thread panic: attempt to use null value

Example:

const x: ?i32 = null;
const y = x.?;

Use orelse or if.

const y = x orelse 0;

G.7 Error Ignored

error: error is ignored

Example:

file.writeAll(data);

The function returns an error union.

Handle it:

try file.writeAll(data);

Or:

file.writeAll(data) catch {};

Zig requires explicit error handling.

G.8 Expected Error Union Type

error: expected error union type

Example:

const x = try 123;

try applies only to error unions.

Correct:

const x = try parse();

G.9 Slice and Array Mismatch

error: expected type '[]u8', found '[16]u8'

An array and a slice are different types.

Array:

[16]u8

Slice:

[]u8

Convert with slicing:

const slice = array[0..];

G.10 Cannot Assign to Constant

error: cannot assign to constant

Example:

const x = 10;
x = 20;

Use var if mutation is required.

var x = 10;

G.11 Division by Zero

thread panic: division by zero

Example:

const x = a / b;

Check the divisor before division.

if (b == 0) {
    return error.DivideByZero;
}

G.12 Integer Overflow

thread panic: integer overflow

In safe builds, overflow traps.

Example:

const x: u8 = 255;
const y = x + 1;

Use wrapping arithmetic if wraparound is intended.

const y = x +% 1;

G.13 Pointer Alignment Error

error: cast increases pointer alignment

Example:

const p: *u8 = ...;
const q: *u32 = @ptrCast(p);

The compiler cannot prove the alignment.

Use @alignCast when alignment is guaranteed.

const q: *u32 = @alignCast(@ptrCast(p));

G.14 Invalid Enum Value

error: enum value not in range

Example:

const x: Color = @enumFromInt(99);

Validate integers before conversion.

G.15 Switch Must Handle All Cases

error: switch must handle all possibilities

Example:

switch (x) {
    0 => zero(),
}

Add missing cases or else.

switch (x) {
    0 => zero(),
    else => other(),
}

G.16 Missing Return

error: expected type 'i32', found 'void'

Or:

error: control reaches end of function

Example:

fn add(a: i32, b: i32) i32 {
    a + b;
}

Use return.

return a + b;

G.17 Recursive Type Has Infinite Size

error: struct depends on itself

Example:

const Node = struct {
    next: Node,
};

Use a pointer.

const Node = struct {
    next: ?*Node,
};

G.18 No Member Named

error: no field or member function named

Example:

point.z

Check the declaration or imported module.

G.19 Unable to Resolve Comptime Value

error: unable to resolve comptime value

Example:

const n = runtimeValue();
const T = [n]u8;

Array lengths and types often require compile-time values.

Use runtime allocation instead.

G.20 Dependency Loop

error: dependency loop detected

Example:

a imports b
b imports a

Move shared declarations into a third module.

G.21 Out of Bounds Access

thread panic: index out of bounds

Example:

const x = items[10];

Check .len.

if (i < items.len) {
    use(items[i]);
}

G.22 Allocation Leaks

In debug builds, allocators may report leaks.

Example:

const p = try allocator.alloc(u8, 100);

Missing:

allocator.free(p);

Use defer.

const p = try allocator.alloc(u8, 100);
defer allocator.free(p);

G.23 Common Rule

Most Zig compiler errors come from four ideas:

explicit ownership
explicit mutability
explicit error handling
explicit types

The language usually rejects code where one of these became unclear.