---
title: "Erros no build.zig — Resolver Problemas do Build System"
url: "https://ziglang.com.br/troubleshooting/erros-no-build.zig-resolver-problemas-do-build-system/"
markdown_url: "https://ziglang.com.br/troubleshooting/erros-no-build.zig-resolver-problemas-do-build-system.MD"
description: "Guia para resolver erros no build.zig do Zig. Erros de configuração, dependências, steps, módulos e problemas comuns do sistema de build."
date: "2026-02-21"
author: "Zig Brasil"
---

# Erros no build.zig — Resolver Problemas do Build System

Guia para resolver erros no build.zig do Zig. Erros de configuração, dependências, steps, módulos e problemas comuns do sistema de build.


# Erros no build.zig — Resolver Problemas do Build System

O build.zig é código Zig que configura o processo de compilação. Quando ele falha, o projeto inteiro não compila. Este guia cobre os erros mais comuns e suas soluções.

## Erro: "build.zig has errors"

**Causa:** Erro de sintaxe ou lógica no build.zig.

```bash
# Ver o erro exato
zig build 2>&1

# Exemplo de saída:
# build.zig:15:5: error: expected expression, found '}'
```

**Solução:** Trate build.zig como qualquer outro arquivo Zig — leia a mensagem de erro, verifique a linha indicada e corrija o problema.

## Erro: "unable to find build.zig"

```bash
# Verificar se está no diretório correto
ls build.zig

# Se não existe, criar um:
zig init

# Ou especificar o caminho:
zig build --build-file /caminho/para/build.zig
```

## Erro: "unable to resolve dependency"

**Causa:** Dependência declarada no `build.zig.zon` não foi encontrada.

```bash
# Baixar/atualizar dependências
zig fetch --save https://github.com/user/lib/archive/v1.0.tar.gz

# Se o hash está errado:
# O erro mostrará o hash esperado — copie e atualize no build.zig.zon
```

```zig
// build.zig.zon — verificar formato
.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{
        .minha_dep = .{
            .url = "https://github.com/user/lib/archive/v1.0.tar.gz",
            .hash = "1220abc...", // Hash correto fornecido pelo erro
        },
    },
    .paths = .{"."},
}
```

## Erro: "module not found"

**Causa:** Tentando importar um módulo que não foi registrado no build.zig.

```zig
// No build.zig — registrar o módulo corretamente
const dep = b.dependency("minha_dep", .{
    .target = target,
    .optimize = optimize,
});

// Adicionar o módulo ao executável
exe.root_module.addImport("minha_dep", dep.module("minha_dep"));
```

Verifique se o nome do módulo no `addImport` corresponde ao que a dependência exporta.

## Erro: "step has no dependencies"

**Causa:** Step declarado mas não conectado ao grafo de build.

```zig
// PROBLEMA: step não conectado
const meu_step = b.step("deploy", "Deploy");
// Faltou: meu_step.dependOn(...)

// SOLUÇÃO:
const meu_step = b.step("deploy", "Deploy");
const run = b.addRunArtifact(exe);
meu_step.dependOn(&run.step);
```

## Erro: API Mudou entre Versões

As mudanças mais comuns ao atualizar o Zig:

### 0.11 para 0.12+
```zig
// ANTIGO (0.11):
// exe.addPackagePath("modulo", "src/modulo.zig");

// NOVO (0.12+):
exe.root_module.addImport("modulo", b.addModule(.{
    .name = "modulo",
    .root_source_file = b.path("src/modulo.zig"),
}));
```

### Mudanças de path
```zig
// ANTIGO:
// .root_source_file = .{ .path = "src/main.zig" },

// NOVO:
.root_source_file = b.path("src/main.zig"),
```

Consulte o changelog da versão para todas as mudanças de API.

## Erro: "duplicate module"

**Causa:** O mesmo módulo foi adicionado duas vezes.

```zig
// PROBLEMA: duplicata
exe.root_module.addImport("utils", modulo_utils);
exe.root_module.addImport("utils", modulo_utils); // ERRO!

// SOLUÇÃO: adicionar apenas uma vez
exe.root_module.addImport("utils", modulo_utils);
```

## Problema: Testes Não São Encontrados

```zig
// Verificar se o step de teste está configurado
const unit_tests = b.addTest(.{
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});

const run_tests = b.addRunArtifact(unit_tests);
const test_step = b.step("test", "Rodar testes");
test_step.dependOn(&run_tests.step);
```

```bash
# Rodar testes
zig build test

# Ver quais steps estão disponíveis
zig build --help
```

## Problema: Custom Steps com Erros

```zig
// Step customizado que roda comando externo
const cmd = b.addSystemCommand(&.{ "echo", "Hello" });

// Adicionar dependência a outro step
cmd.step.dependOn(&exe.step);

// Criar step nomeado
const custom_step = b.step("custom", "Meu step");
custom_step.dependOn(&cmd.step);
```

## Problema: Variáveis de Build

```zig
// Adicionar opções customizadas ao build
const porta = b.option(u16, "porta", "Porta do servidor") orelse 8080;

// Passar opção para o código Zig via @import("config")
const options = b.addOptions();
options.addOption(u16, "porta", porta);
exe.root_module.addOptions("config", options);
```

```zig
// No código Zig:
const config = @import("config");
const porta: u16 = config.porta;
```

```bash
# Usar a opção
zig build -Dporta=3000
```

## Diagnóstico

```bash
# Ver todos os steps disponíveis
zig build --help

# Compilação verbose
zig build --verbose

# Limpar cache e tentar novamente
rm -rf zig-cache .zig-cache zig-out && zig build

# Verificar a versão do Zig (APIs mudam entre versões)
zig version
```

## Checklist de Resolução

1. Leia a mensagem de erro completa — build.zig é código Zig normal
2. Verifique se `build.zig.zon` tem hashes corretos
3. Limpe o cache: `rm -rf zig-cache .zig-cache zig-out`
4. Verifique se a versão do Zig é compatível com o projeto
5. Consulte o changelog ao atualizar versões
6. Use `zig build --verbose` para mais detalhes

## Veja Também

- [FAQ Build System](/faq/faq-build-system/) — Perguntas sobre o build system
- [Compilação Lenta](/troubleshooting/zig-lento-compilar/) — Otimizar compilação
- [Falha em Dependências](/troubleshooting/zig-dependencia-falha/) — Problemas com packages
- [Zig Não Compila](/troubleshooting/zig-nao-compila/) — Erros de compilação
- [Atualizar Versão](/troubleshooting/zig-atualizar-versao/) — Migrar entre versões