---
title: "Zig Não Compila — Soluções para Erros de Compilação"
url: "https://ziglang.com.br/troubleshooting/zig-n%C3%A3o-compila-solu%C3%A7%C3%B5es-para-erros-de-compila%C3%A7%C3%A3o/"
markdown_url: "https://ziglang.com.br/troubleshooting/zig-n%C3%A3o-compila-solu%C3%A7%C3%B5es-para-erros-de-compila%C3%A7%C3%A3o.MD"
description: "Guia completo para resolver erros de compilação em Zig: erros de tipo, variáveis não usadas, imports falhando e os erros mais comuns com soluções. Em português."
date: "2026-02-21"
author: "Zig Brasil"
---

# Zig Não Compila — Soluções para Erros de Compilação

Guia completo para resolver erros de compilação em Zig: erros de tipo, variáveis não usadas, imports falhando e os erros mais comuns com soluções. Em português.


# 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:**
```zig
// 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:**
```zig
// 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:**
```zig
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:**
```zig
// 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:**
```zig
// 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:**
```zig
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:**
```zig
// 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:**
```zig
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:**
```zig
// 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

1. **Leia a mensagem inteira** — Zig mostra exatamente a linha e coluna do erro
2. **Siga a cadeia de erros** — Muitas vezes o primeiro erro causa os seguintes
3. **Verifique os tipos** — `@TypeOf(variavel)` ou `@compileLog(@TypeOf(x))` para debug
4. **Compile com `zig build-exe`** para erros mais detalhados que `zig build`
5. **Use `@compileLog`** para debugging em comptime

## Veja Também

- [Erros do Compilador](/erros/) — Referência completa de erros
- [Sintaxe Básica](/cheatsheets/sintaxe-basica/) — Fundamentos da linguagem
- [Error Handling](/cheatsheets/error-handling/) — Tratamento de erros
- [Tipos de Dados](/cheatsheets/tipos-dados/) — Sistema de tipos de Zig
- [FAQ Iniciantes](/faq/faq-iniciantes/) — Perguntas de quem está começando