--- title: "Dependency Fetch Failed — Como Resolver em Zig" url: "https://ziglang.com.br/erros/dependency-fetch-failed-como-resolver-em-zig/" markdown_url: "https://ziglang.com.br/erros/dependency-fetch-failed-como-resolver-em-zig.MD" description: "Entenda o erro de falha ao buscar dependências em Zig (zig fetch). Veja como configurar build.zig.zon e resolver problemas de download." date: "2026-02-21" author: "Zig Brasil" --- # Dependency Fetch Failed — Como Resolver em Zig Entenda o erro de falha ao buscar dependências em Zig (zig fetch). Veja como configurar build.zig.zon e resolver problemas de download. # Dependency Fetch Failed — Como Resolver em Zig ## O Que Este Erro Significa O erro de falha ao buscar dependências ocorre quando o sistema de build do Zig não consegue baixar ou validar uma dependência declarada no `build.zig.zon`. Isso pode acontecer por problemas de rede, URL incorreta, hash de integridade inválido ou formato incorreto do manifesto. Mensagens típicas: ``` error: unable to fetch dependency ``` ``` error: hash mismatch ``` ``` error: unable to resolve dependency ``` O sistema de pacotes do Zig usa hashes de integridade para garantir reprodutibilidade — cada dependência é identificada por um hash exato do seu conteúdo. ## Causas Comuns ### 1. URL Incorreta no build.zig.zon ```zig // build.zig.zon .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .minha_lib = .{ .url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz", // URL pode estar errada ou o repositório foi removido .hash = "12209876543210abcdef...", }, }, } ``` ### 2. Hash Incorreto ou Desatualizado ```zig // build.zig.zon .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .zap = .{ .url = "https://github.com/zigtools/zap/archive/v0.1.0.tar.gz", .hash = "1220aaaabbbbccccdddd...", // Hash antigo ou errado // ERRO: hash mismatch — conteúdo não bate }, }, } ``` ### 3. Sem Conexão de Rede ```bash $ zig build # ERRO: unable to connect to github.com — sem internet ``` ### 4. Manifesto build.zig.zon Malformado ```zig // build.zig.zon — ERRO DE SINTAXE .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .lib = .{ .url = "https://example.com/lib.tar.gz" // Falta vírgula e hash! }, }, } ``` ### 5. Versão do Zig Incompatível com a Dependência ```bash # A dependência requer Zig 0.12.0, mas você tem 0.11.0 $ zig build # ERRO: dependency requires newer Zig version ``` ## Como Corrigir ### Solucao 1: Usar zig fetch para Obter o Hash Correto ```bash # O Zig calcula o hash automaticamente $ zig fetch https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz # Saída: 1220abcdef1234567890... # Copie este hash para o build.zig.zon ``` ### Solucao 2: Remover Hash e Deixar Zig Calcular ```zig // build.zig.zon — remova o hash temporariamente .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .minha_lib = .{ .url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz", // Sem hash — zig build mostrará o hash correto no erro }, }, } ``` ```bash $ zig build # error: hash not provided; expected: 1220abcdef... # Copie o hash sugerido e cole no build.zig.zon ``` ### Solucao 3: Verificar e Corrigir a URL ```zig // build.zig.zon .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .minha_lib = .{ // Use a URL do archive do GitHub (não do repositório) .url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz", .hash = "1220...", }, }, } ``` URLs válidas para dependências: ``` # GitHub release https://github.com/user/repo/archive/refs/tags/v1.0.0.tar.gz # GitHub commit específico https://github.com/user/repo/archive/abc123def.tar.gz # Tarball direto https://example.com/lib-1.0.0.tar.gz ``` ### Solucao 4: Usar Dependência Local (Desenvolvimento) ```zig // build.zig.zon — para desenvolvimento local .{ .name = "meu-projeto", .version = "0.1.0", .dependencies = .{ .minha_lib = .{ .path = "../minha-lib", // Caminho local — sem download }, }, } ``` ### Solucao 5: Configurar Proxy ou Cache ```bash # Se estiver atrás de proxy $ export HTTPS_PROXY=http://proxy:8080 $ zig build # Limpar cache de pacotes $ rm -rf ~/.cache/zig $ zig build ``` ### Solucao 6: Usar a Dependência no build.zig Após declarar no `build.zig.zon`, use no `build.zig`: ```zig // build.zig const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Buscar dependência declarada no build.zig.zon const dep = b.dependency("minha_lib", .{ .target = target, .optimize = optimize, }); const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Adicionar módulo da dependência exe.root_module.addImport("minha_lib", dep.module("minha_lib")); b.installArtifact(exe); } ``` ## build.zig.zon Completo de Exemplo ```zig .{ .name = "meu-projeto", .version = "0.1.0", .minimum_zig_version = "0.13.0", .dependencies = .{ .zap = .{ .url = "https://github.com/zigtools/zap/archive/refs/tags/v0.2.0.tar.gz", .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678", }, .minha_lib_local = .{ .path = "../minha-lib", }, }, .paths = .{ "build.zig", "build.zig.zon", "src", }, } ``` ## Diagnóstico ```bash # Verificar versão do Zig $ zig version # Testar download manual $ curl -L -o test.tar.gz "URL_DA_DEPENDENCIA" $ sha256sum test.tar.gz # Verificar cache $ ls ~/.cache/zig/ # Rebuild limpo $ rm -rf zig-out .zig-cache $ zig build ``` ## Erros Relacionados - [build.zig not found](/erros/erro-build-zig-not-found/) — Arquivo de build não encontrado - [Linker error](/erros/erro-linker-error/) — Erro de linker - [Target not supported](/erros/erro-target-not-supported/) — Alvo não suportado ## Links Úteis - [Documentação oficial do Zig — Package Management](https://ziglang.org/documentation/master/#Package-Management) - [Receitas de configuração de dependências](/receitas/) - [Tutorial sobre o build system do Zig](/tutoriais/)