---
title: "Falha em Dependências Zig — Resolver Problemas com Packages"
url: "https://ziglang.com.br/troubleshooting/falha-em-depend%C3%AAncias-zig-resolver-problemas-com-packages/"
markdown_url: "https://ziglang.com.br/troubleshooting/falha-em-depend%C3%AAncias-zig-resolver-problemas-com-packages.MD"
description: "Guia para resolver problemas com dependências e pacotes em Zig. Erros de fetch, hash inválido, build.zig.zon, versões incompatíveis e cache de dependências."
date: "2026-02-21"
author: "Zig Brasil"
---

# Falha em Dependências Zig — Resolver Problemas com Packages

Guia para resolver problemas com dependências e pacotes em Zig. Erros de fetch, hash inválido, build.zig.zon, versões incompatíveis e cache de dependências.


# Falha em Dependências Zig — Resolver Problemas com Packages

O gerenciador de pacotes do Zig é integrado ao build system. Quando dependências falham, geralmente é por problemas de rede, hash incorreto ou versões incompatíveis. Este guia resolve os problemas mais comuns.

## Erro: "hash mismatch"

**Causa:** O hash no `build.zig.zon` não corresponde ao conteúdo baixado.

```
error: hash mismatch: expected 1220abc..., found 1220def...
```

**Solução:**
```bash
# Opção 1: Usar o hash correto da mensagem de erro
# Copie o hash "found" e substitua no build.zig.zon

# Opção 2: Usar zig fetch para calcular o hash correto
zig fetch https://github.com/user/lib/archive/v1.0.tar.gz
# Saída: 1220def...

# Opção 3: Fetch e salvar automaticamente
zig fetch --save https://github.com/user/lib/archive/v1.0.tar.gz
```

Atualize o hash no `build.zig.zon`:
```zig
.minha_dep = .{
    .url = "https://github.com/user/lib/archive/v1.0.tar.gz",
    .hash = "1220def...", // Hash corrigido
},
```

## Erro: "unable to fetch"

**Causa:** Problema de rede ou URL inválida.

```bash
# Verificar se a URL é acessível
curl -I https://github.com/user/lib/archive/v1.0.tar.gz

# Verificar conectividade
ping github.com

# Se atrás de proxy:
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080
zig build
```

**URLs comuns que mudam:**
```zig
// GitHub — usar formato de archive correto
.url = "https://github.com/USER/REPO/archive/refs/tags/v1.0.tar.gz",
// ou
.url = "https://github.com/USER/REPO/archive/COMMIT_HASH.tar.gz",
```

## Erro: "dependency build failure"

**Causa:** A dependência baixou corretamente mas falha ao compilar.

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

# Causas comuns:
# 1. Versão do Zig incompatível com a dependência
# 2. Target não suportado pela dependência
# 3. Dependência transitiva faltando
```

**Soluções:**
```zig
// Verificar se a dependência suporta sua versão do Zig
// No build.zig.zon da dependência, veja .minimum_zig_version

// Usar uma versão específica da dependência compatível com seu Zig
.minha_dep = .{
    .url = "https://github.com/user/lib/archive/v0.5.0.tar.gz", // versão compatível
    .hash = "...",
},
```

## Erro: "module not found in dependency"

**Causa:** O nome do módulo no `addImport` não corresponde ao que a dependência exporta.

```zig
// Verificar o build.zig da dependência para saber o nome do módulo
const dep = b.dependency("httpz", .{
    .target = target,
    .optimize = optimize,
});

// O nome aqui deve corresponder ao que a dep exporta
exe.root_module.addImport("httpz", dep.module("httpz"));
// Se o erro diz "module 'httpz' not found", tente:
// dep.module("http") — pode ter outro nome
```

Consulte a documentação ou o `build.zig` da dependência para ver os nomes corretos dos módulos exportados.

## Problema: Cache de Dependências Corrompido

```bash
# Limpar cache global de pacotes
rm -rf ~/.cache/zig

# Limpar cache local
rm -rf zig-cache .zig-cache

# Recompilar
zig build
```

## Problema: Dependência com Subdependências

```zig
// Se a dependência tem suas próprias dependências,
// elas são resolvidas automaticamente.
// Mas se houver conflitos:

// No build.zig.zon — sobrescrever dependência transitiva
.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{
        .minha_dep = .{
            .url = "...",
            .hash = "...",
        },
        // Sobrescrever subdependência se necessário
        .sub_dep = .{
            .url = "...",
            .hash = "...",
        },
    },
    .paths = .{"."},
}
```

## Problema: Dependência Local (durante desenvolvimento)

```zig
// build.zig.zon — usar caminho local durante desenvolvimento
.{
    .dependencies = .{
        .minha_dep = .{
            .path = "../minha-lib", // Caminho local
        },
    },
}
```

Caminhos locais são úteis durante desenvolvimento mas não devem ser commitados para produção. Use URLs para distribuição.

## Problema: Versão do Zig Incompatível

```bash
# Verificar versão do Zig
zig version

# Verificar versão mínima exigida pela dependência
# Geralmente documentada no README ou build.zig.zon
```

Se a dependência requer uma versão mais nova do Zig:
1. Atualize o Zig para a versão requerida
2. Ou use uma versão anterior da dependência compatível com seu Zig

## Diagnóstico

```bash
# Ver o que zig build está fazendo
zig build --verbose

# Testar apenas o fetch das dependências
zig fetch https://url/do/pacote.tar.gz

# Verificar build.zig.zon (deve ser JSON-like válido)
cat build.zig.zon

# Listar dependências resolvidas
zig build --verbose 2>&1 | grep -i "fetch\|depend"
```

## Checklist de Resolução

1. Verifique se a URL da dependência é acessível
2. Atualize o hash com `zig fetch --save URL`
3. Limpe o cache: `rm -rf zig-cache .zig-cache ~/.cache/zig`
4. Verifique compatibilidade de versão do Zig
5. Confira o nome correto do módulo no build.zig da dependência
6. Para cross-compilation, verifique se a dependência suporta o target

## Veja Também

- [FAQ Build System](/faq/faq-build-system/) — Gerenciar dependências
- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Problemas do build system
- [FAQ Ecossistema](/faq/faq-ecossistema/) — Onde encontrar pacotes
- [Atualizar Versão](/troubleshooting/zig-atualizar-versao/) — Migrar entre versões
- [Receitas](/receitas/) — Exemplos com dependências externas