Erros Comuns em Zig — Guia de Referência e Soluções

Bem-vindo ao guia completo de erros da linguagem Zig em português brasileiro. Esta página reúne os erros mais frequentes que desenvolvedores encontram ao programar em Zig, organizados por categoria. Cada página de erro contém uma explicação clara do problema, exemplos de código que causam o erro e soluções práticas para corrigi-lo.

Como Usar Este Guia

Se você recebeu uma mensagem de erro do compilador ou encontrou um comportamento inesperado em tempo de execução, procure o erro correspondente nas categorias abaixo. Cada página foi escrita para ser encontrada facilmente via busca — então você também pode pesquisar diretamente pelo texto do erro.

Erros de Tempo de Compilação

Esses erros são detectados pelo compilador antes mesmo do seu programa ser executado. São os mais comuns para quem está começando.

• expected type ‘X’, found ‘Y’ — Tipos incompatíveis em expressões
• unused local variable / unused const — Variáveis declaradas e não utilizadas
• undeclared identifier — Identificador não declarado no escopo
• expected expression — Expressão esperada pelo compilador
• expected ‘;’ — Ponto e vírgula ausente
• type mismatch in assignment — Incompatibilidade de tipo em atribuição
• cannot assign to constant — Tentativa de modificar uma constante
• expected return expression — Expressão de retorno ausente
• unreachable code — Código inalcançável detectado
• shadows declaration from outer scope — Sombreamento de variável
• integer overflow at comptime — Overflow de inteiro em tempo de compilação
• ambiguous reference — Referência ambígua em imports
• expected ‘}’ — Chave de fechamento ausente
• invalid character in source — Caractere inválido no código-fonte
• expected block expression — Bloco de expressão esperado

Erros de Tempo de Execução (Runtime)

Esses erros acontecem enquanto o programa está rodando. Geralmente envolvem acesso inválido à memória ou operações matemáticas proibidas.

• index out of bounds — Índice fora dos limites do array ou slice
• attempt to unwrap null optional — Tentativa de desempacotar optional nulo
• integer overflow at runtime — Overflow de inteiro em tempo de execução
• division by zero — Divisão por zero
• stack overflow — Estouro de pilha
• OutOfMemory — Memória insuficiente
• Segmentation fault — Falha de segmentação / acesso ilegal à memória
• Use after free — Uso de memória após liberação
• Double free — Liberação dupla de memória
• Memory leak (GPA) — Detecção de vazamento de memória

Erros de Error Union e Optional

Esses erros estão relacionados ao sistema de tratamento de erros do Zig, uma de suas funcionalidades mais poderosas.

• error not handled — Erro não tratado
• try in function that doesn’t return error — Uso de try em função sem retorno de erro
• catch reached unreachable — Catch alcançou código inalcançável
• attempt to unwrap error — Tentativa de desempacotar erro
• error payload not used — Payload do erro não utilizado

Erros do Sistema de Tipos

O sistema de tipos do Zig é rigoroso por design. Esses erros ajudam a prevenir bugs sutis.

• type coercion failed — Falha na coerção de tipo
• pointer cast has misaligned address — Cast de ponteiro com endereço desalinhado
• integer truncation — Truncamento de inteiro
• signed/unsigned mismatch — Incompatibilidade signed/unsigned
• slice type mismatches — Incompatibilidade de tipos de slice
• sentinel value mismatches — Incompatibilidade de valores sentinela
• packed struct layout issues — Problemas de layout em packed struct

Erros do Sistema de Build

Erros relacionados ao sistema de build, dependências e compilação cruzada do Zig.

• build.zig not found — Arquivo build.zig não encontrado
• dependency fetch failures — Falha ao baixar dependências
• linker errors — Erros do linker (símbolo indefinido)
• @cImport failures — Falhas no @cImport
• cross-compilation target errors — Erros de alvo de compilação cruzada

Erros de Memória e Alocadores

O gerenciamento manual de memória do Zig oferece controle total, mas exige atenção.

• invalid free — Liberação inválida de memória
• memory leak detected — Vazamento de memória detectado pelo alocador
• buffer overrun — Estouro de buffer
• alignment errors — Erros de alinhamento de memória

Erros Comuns de Iniciantes

Armadilhas típicas para quem está aprendendo Zig, especialmente vindo de outras linguagens.

• Comparar strings com == — A forma errada de comparar strings
• Esquecer defer — Vazamento de recursos por falta de defer
• Capturar ponteiro em for loop — Ponteiro capturado em laço for
• Retornar ponteiro para variável local — Ponteiro dangling ao retornar variável local
• Confundir comptime vs runtime — Diferença entre tempo de compilação e execução

Dicas Gerais de Debug em Zig

1. Leia a mensagem de erro completa — O compilador do Zig é famoso por suas mensagens de erro claras e detalhadas. Leia todas as linhas, incluindo as notas auxiliares.

2. Use @compileLog — Para depurar expressões em tempo de compilação, use @compileLog(valor) para imprimir valores durante a compilação.

3. Use std.debug.print — Para depuração em tempo de execução, imprima valores com std.debug.print("valor: {}\n", .{variavel}).

4. Ative o GeneralPurposeAllocator — O GPA detecta vazamentos de memória, double-free e use-after-free automaticamente durante o desenvolvimento.

5. Consulte a documentação oficial — A documentação oficial do Zig é a referência mais completa e atualizada.

Este guia é mantido pela comunidade Zig Brasil. Se você encontrou um erro ou quer contribuir com uma nova página, entre em contato conosco.