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
• unreachable code — Código inalcançável detectado

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.

• 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
• OutOfMemory — Memória insuficiente
• 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.

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
• slice type mismatches — Incompatibilidade de tipos de slice
• 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.

• memory leak detected — Vazamento de memória detectado pelo alocador

Erros Comuns de Iniciantes

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

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.