Zig Não Compila — Soluções para Erros de Compilação
Este guia cobre os erros de compilação mais comuns em Zig e como resolvê-los. Zig é conhecido por suas mensagens de erro claras e detalhadas — aprenda a lê-las corretamente e resolverá a maioria dos problemas rapidamente.
Erro: “unused local variable”
Mensagem: error: local variable 'x' is never used
Causa: Zig não permite variáveis declaradas mas nunca usadas.
Solução:
// ERRO:
var x: i32 = 42;
// SOLUÇÃO 1: Descartar explicitamente
var x: i32 = 42;
_ = x;
// SOLUÇÃO 2: Usar underscore na declaração
_ = funcaoQueRetorna();
// SOLUÇÃO 3: Usar const se não vai mudar
const x: i32 = 42;
// ...usar x...
Erro: “unused function parameter”
Mensagem: error: unused function parameter 'allocator'
Solução:
// ERRO:
fn processar(allocator: std.mem.Allocator, dados: []u8) void {
// não usa allocator
}
// SOLUÇÃO: Descartar com _
fn processar(allocator: std.mem.Allocator, dados: []u8) void {
_ = allocator;
// ...usar dados...
}
Erro: “expected type X, found Y”
Mensagem: error: expected type 'u32', found 'i32'
Causa: Zig é rigoroso com tipos — não faz conversão implícita.
Solução:
const x: i32 = 42;
// ERRO:
// const y: u32 = x;
// SOLUÇÃO: Cast explícito
const y: u32 = @intCast(x);
// Para floats:
const f: f64 = 3.14;
const g: f32 = @floatCast(f);
// Para int <-> float:
const i: i32 = @intFromFloat(f);
const h: f64 = @floatFromInt(x);
Erro: “cannot evaluate comptime expression”
Mensagem: error: unable to evaluate comptime expression
Causa: Tentativa de usar valor de runtime em contexto que requer comptime.
Solução:
// ERRO: tamanho de array precisa ser comptime
fn criarArray(tamanho: usize) void {
// var arr: [tamanho]u8 = undefined; // ERRO!
}
// SOLUÇÃO 1: Usar comptime
fn criarArray(comptime tamanho: usize) [tamanho]u8 {
return undefined;
}
// SOLUÇÃO 2: Usar alocação dinâmica
fn criarBuffer(allocator: std.mem.Allocator, tamanho: usize) ![]u8 {
return allocator.alloc(u8, tamanho);
}
Erro: “error.XXX not handled”
Mensagem: error: error is not handled
Causa: Funções que retornam erros precisam ter o erro tratado.
Solução:
// ERRO:
// const dados = std.fs.cwd().readFileAlloc(alloc, "file.txt", 1e6);
// SOLUÇÃO 1: Usar try (propagar o erro)
const dados = try std.fs.cwd().readFileAlloc(alloc, "file.txt", 1e6);
// SOLUÇÃO 2: Usar catch (tratar o erro)
const dados = std.fs.cwd().readFileAlloc(alloc, "file.txt", 1e6) catch |err| {
std.debug.print("Erro: {}\n", .{err});
return;
};
// SOLUÇÃO 3: Usar catch com valor padrão
const valor = funcao() catch 0;
Erro: “access of null pointer”
Mensagem: error: access of null value
Causa: Tentativa de usar valor optional sem desempacotar.
Solução:
const maybe_valor: ?i32 = null;
// ERRO:
// const x = maybe_valor + 1;
// SOLUÇÃO 1: if com capture
if (maybe_valor) |valor| {
const x = valor + 1;
_ = x;
}
// SOLUÇÃO 2: orelse
const x = maybe_valor orelse 0;
_ = x;
// SOLUÇÃO 3: .? (panic se null — use apenas quando tem certeza)
// const x = maybe_valor.?;
Erro: “@import file not found”
Mensagem: error: unable to open file 'modulo.zig'
Causa: Caminho do arquivo importado está errado ou arquivo não existe.
Solução:
// Verificar caminho relativo ao arquivo atual
const modulo = @import("modulo.zig"); // mesmo diretório
const sub = @import("sub/modulo.zig"); // subdiretório
const std = @import("std"); // biblioteca padrão
// No build.zig, verificar root_source_file
.root_source_file = b.path("src/main.zig"), // caminho correto
Erro: “integer overflow”
Mensagem: error: integer overflow
Causa: Operação aritmética excede o range do tipo.
Solução:
const x: u8 = 255;
// ERRO em runtime (debug mode):
// const y = x + 1; // overflow!
// SOLUÇÃO 1: Usar tipo maior
const y: u16 = @as(u16, x) + 1;
// SOLUÇÃO 2: Wrapping arithmetic
const y = x +% 1; // wraps to 0
// SOLUÇÃO 3: Saturating arithmetic
const y = x +| 1; // satura em 255
Erro: “variable ‘x’ used as a type”
Mensagem: error: expected type 'type', found 'comptime_int'
Causa: Usar variável onde o compilador espera um tipo.
Solução:
// ERRO:
// const tamanho = 10;
// var arr: [tamanho]u8 = undefined; // funciona se tamanho é const/comptime
// Se for parâmetro de função:
fn f(comptime n: usize) [n]u8 { // precisa ser comptime
return undefined;
}
Dicas Gerais
- Leia a mensagem inteira — Zig mostra exatamente a linha e coluna do erro
- Siga a cadeia de erros — Muitas vezes o primeiro erro causa os seguintes
- Verifique os tipos —
@TypeOf(variavel)ou@compileLog(@TypeOf(x))para debug - Compile com
zig build-exepara erros mais detalhados quezig build - Use
@compileLogpara debugging em comptime
Veja Também
- Erros do Compilador — Referência completa de erros
- Sintaxe Básica — Fundamentos da linguagem
- Error Handling — Tratamento de erros
- Tipos de Dados — Sistema de tipos de Zig
- FAQ Iniciantes — Perguntas de quem está começando