# Appendix G. Common Compiler Errors

### 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

```text
error: unused local constant
```

Example:

```zig
const x = 10;
```

Zig does not allow unused local declarations.

Use the value:

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

Or discard it explicitly:

```zig
_ = x;
```

### G.2 Unused Function Parameter

```text
error: unused function parameter
```

Example:

```zig
fn f(x: i32) void {}
```

Discard it explicitly:

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

### G.3 Variable Never Mutated

```text
error: local variable is never mutated
```

Example:

```zig
var x = 10;
```

Use `const` instead:

```zig
const x = 10;
```

Zig distinguishes mutable and immutable storage strictly.

### G.4 Expected Type, Found Type

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

Example:

```zig
const x: u32 = -1;
```

Or:

```zig
const x: u32 = y;
```

Use an explicit cast when the conversion is valid.

```zig
const x: u32 = @intCast(y);
```

The compiler requires explicit narrowing or signedness conversion.

### G.5 Expected Optional Type

```text
error: expected optional type
```

Example:

```zig
const x: i32 = 10;

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

Optional capture works only on optional values.

Correct:

```zig
const x: ?i32 = 10;
```

### G.6 Optional Unwrap Failed

```text
thread panic: attempt to use null value
```

Example:

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

Use `orelse` or `if`.

```zig
const y = x orelse 0;
```

### G.7 Error Ignored

```text
error: error is ignored
```

Example:

```zig
file.writeAll(data);
```

The function returns an error union.

Handle it:

```zig
try file.writeAll(data);
```

Or:

```zig
file.writeAll(data) catch {};
```

Zig requires explicit error handling.

### G.8 Expected Error Union Type

```text
error: expected error union type
```

Example:

```zig
const x = try 123;
```

`try` applies only to error unions.

Correct:

```zig
const x = try parse();
```

### G.9 Slice and Array Mismatch

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

An array and a slice are different types.

Array:

```zig
[16]u8
```

Slice:

```zig
[]u8
```

Convert with slicing:

```zig
const slice = array[0..];
```

### G.10 Cannot Assign to Constant

```text
error: cannot assign to constant
```

Example:

```zig
const x = 10;
x = 20;
```

Use `var` if mutation is required.

```zig
var x = 10;
```

### G.11 Division by Zero

```text
thread panic: division by zero
```

Example:

```zig
const x = a / b;
```

Check the divisor before division.

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

### G.12 Integer Overflow

```text
thread panic: integer overflow
```

In safe builds, overflow traps.

Example:

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

Use wrapping arithmetic if wraparound is intended.

```zig
const y = x +% 1;
```

### G.13 Pointer Alignment Error

```text
error: cast increases pointer alignment
```

Example:

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

The compiler cannot prove the alignment.

Use `@alignCast` when alignment is guaranteed.

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

### G.14 Invalid Enum Value

```text
error: enum value not in range
```

Example:

```zig
const x: Color = @enumFromInt(99);
```

Validate integers before conversion.

### G.15 Switch Must Handle All Cases

```text
error: switch must handle all possibilities
```

Example:

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

Add missing cases or `else`.

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

### G.16 Missing Return

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

Or:

```text
error: control reaches end of function
```

Example:

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

Use `return`.

```zig
return a + b;
```

### G.17 Recursive Type Has Infinite Size

```text
error: struct depends on itself
```

Example:

```zig
const Node = struct {
    next: Node,
};
```

Use a pointer.

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

### G.18 No Member Named

```text
error: no field or member function named
```

Example:

```zig
point.z
```

Check the declaration or imported module.

### G.19 Unable to Resolve Comptime Value

```text
error: unable to resolve comptime value
```

Example:

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

Array lengths and types often require compile-time values.

Use runtime allocation instead.

### G.20 Dependency Loop

```text
error: dependency loop detected
```

Example:

```text
a imports b
b imports a
```

Move shared declarations into a third module.

### G.21 Out of Bounds Access

```text
thread panic: index out of bounds
```

Example:

```zig
const x = items[10];
```

Check `.len`.

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

### G.22 Allocation Leaks

In debug builds, allocators may report leaks.

Example:

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

Missing:

```zig
allocator.free(p);
```

Use `defer`.

```zig
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.