Catch Missing Struct Fields at Compile Time with Zig comptime

The problem: a field that exists until it doesn't

You refactor a struct, renaming a field. The program compiles. Tests pass. Then a deployment fails because some other module still reads the old name. In many languages, you would solve this with runtime checks, unit tests, or a separate macro system. Zig offers a different option: validate the structure while the compiler is still reading your source.

What comptime actually means

The comptime keyword tells Zig that a value must be known during compilation, not when the program runs. You can apply it to function parameters, variables, or blocks. The compiler evaluates that code during semantic analysis—the phase where it checks types, names, and scopes—before it emits machine code.

This is not C++ templates and it is not a C preprocessor. It is ordinary Zig code, running early. Because it runs in the compiler, you can inspect types, generate declarations, and reject invalid configurations with @compileError before an executable exists.

Worked example: require a struct field at compile time

Suppose you want a helper that refuses to compile unless a struct type has a specific field. The following example uses std.meta.typeInfo to inspect a struct and @compileError to stop compilation if the field is missing.

const std = @import("std");

fn requireField(comptime T: type, comptime field: []const u8) void {
    const info = std.meta.typeInfo(T);
    if (info) |ti| {
        if (ti == .Struct) |struct_info| {
            var found: bool = false;
            for (struct_info.fields) |f| {
                if (std.mem.eql(u8, f.name, field)) {
                    found = true;
                }
            }
            if (!found) {
                @compileError("struct is missing required field: " ++ field);
            }
        }
    }
}

const User = struct {
    id: u32,
    name: []const u8,
};

pub fn main() void {
    requireField(User, "id"); // compiles: "id" exists
    // requireField(User, "email"); // uncomment to trigger a compile error
}

Run this from a terminal with zig run main.zig, replacing main.zig with your file path. No special permissions are required. The first call compiles because User has id. Uncommenting the second call produces a compile-time error naming the missing field. Because the check happens in requireField, no runtime code is generated for it.

To confirm the boundary between compile time and runtime, try passing a runtime variable where a comptime parameter is expected:

fn takesComptime(comptime x: i32) void {}

pub fn main() void {
    var y: i32 = 5;
    // takesComptime(y); // error: expected compile-time constant
}

The compiler rejects this before building an executable. That rejection is the useful part: you catch the mistake while editing, not while debugging production.

Trade-offs and limits

• Heavy use of comptime reflection and code generation can noticeably increase compile times.
• Comptime evaluation runs in a single-threaded, interpreter-like environment. It may not mirror target-platform runtime behavior exactly.
• Some standard library functions and runtime constructs are unavailable inside comptime blocks.
• Comptime failures can be harder to debug than runtime errors because there is no running program to inspect.

A practical way to check your work: run zig version and compare the result against the Zig language reference for your installed release. Comptime and std.meta behavior is well established, but details can shift between versions.

Where to start

Pick one function that accepts a type or a configuration value and mark its parameter comptime. Run zig build and see what the compiler accepts or rejects. Use std.meta sparingly; the goal is to fail early and clearly, not to rebuild the type system at compile time.