Catch Invalid Struct Configurations with Zig Comptime

The Problem: Configuration Errors Belong at Compile Time

Imagine you are deploying a service that reads a database configuration struct. A typo in a field name, a port declared as a string instead of an integer, or a missing required field can slip past review and only surface when the application starts—or worse, after it has been running for hours. In many languages, you would write runtime validation, add tests, and hope the bad configuration never reaches production.

Zig offers a different option: inspect the type itself while the compiler is building the program. If the shape is wrong, the build fails before a binary exists.

What Comptime Actually Does

The comptime keyword tells Zig to evaluate an expression, function parameter, or block during compilation instead of at runtime. When a function parameter is marked comptime T: type, Zig generates a separate version of that function for each type you pass in. This is sometimes called monomorphization.

Inside a comptime context, builtins such as @typeInfo expose the structure of a type. You can iterate over struct fields, read their names and types, and call @compileError to stop the build with a message of your choosing. Errors raised here are compile errors, not runtime panics.

Terms you will see:

• Comptime: compile-time execution in Zig's interpreter.
• Monomorphization: generating type-specific machine code from a generic-like function body.
• @typeInfo: a builtin that returns metadata about a type, such as struct fields or enum tags.

Worked Example: Validate a Database Config Struct

This example checks that a configuration struct has a field named port with type u16. Run the commands in a terminal with Zig installed; no special permissions are required.

const std = @import("std");

const DbConfig = struct {
    host: []const u8,
    port: u16,
    enabled: bool,
};

fn requireU16Port(comptime T: type) void {
    const info = @typeInfo(T);
    if (info != .Struct) {
        @compileError("requireU16Port expects a struct type");
    }

    var found_port: bool = false;
    for (info.Struct.fields) |field| {
        if (std.mem.eql(u8, field.name, "port") and field.type == u16) {
            found_port = true;
        }
    }

    if (!found_port) {
        @compileError("DbConfig must contain a u16 field named port");
    }
}

pub fn main() !void {
    requireU16Port(DbConfig);

    const config = DbConfig{
        .host = "localhost",
        .port = 5432,
        .enabled = true,
    };

    try std.io.getStdOut().writer().printAll("Configured {s}:{d}\n", .{config.host, config.port});
}

Save this as config.zig and compile it:

zig version
zig run config.zig

If the struct is valid, the compiler emits a binary and the program prints the host and port. To see the compile-time check in action, change port: u16 to port: []const u8 or delete the field entirely, then run zig run config.zig again. The build should stop with the @compileError message instead of producing an executable.

Where to run: your local development terminal. Permissions: none beyond normal file access. Risks: none for this read-only compilation example; it does not modify system state.

Trade-Offs and Limitations

Comptime is powerful, but it is not free. The compiler executes arbitrary Zig code while building, so heavy metaprogramming can increase compile times and slow incremental builds in large codebases. Some runtime-only standard library functions and heap allocation patterns are unavailable inside comptime contexts. Debugging comptime logic is also harder than runtime debugging because standard debuggers inspect the generated binary, not the compiler's interpreter.

This technique validates shape—field names and types—not runtime values such as whether a port is actually reachable. Use it for structural guarantees, and keep runtime validation for values that change after compilation.

How to Verify It Works

1. Run zig version and consult your toolchain's release notes; comptime builtins can change between releases.
2. Compile the example with zig run config.zig and confirm it succeeds.
3. Alter the DbConfig struct so port is missing or has the wrong type.
4. Run zig run config.zig again and confirm the build fails with your @compileError message.

If the build still succeeds after breaking the struct, the comptime function is not being invoked or the field comparison is not matching as expected.

Comptime turns structural mistakes into build failures. Start with a single struct validation like the one above, measure your compile times, and expand only where the safety benefit justifies the build cost.