Problemas comuns

Sintomas comuns, a causa e o que fazer. Falso positivo, falso negativo e crash são bugs: abra uma issue.

Instalação

**O link de download dá 404 / install.sh não acha release.** Pré-lançamento: nenhum release foi publicado ainda. Os canais entram no ar na v0.1.0, e as instruções já são as definitivas.

**minisign: not found no install.sh.** O script confere o SHA-256 sempre e a assinatura minisign só se o minisign estiver instalado. Instale-o (brew install minisign / apt install minisign) para a verificação completa. Ver Cadeia de suprimento.

**codafort: command not found depois do script.** O script instala em ~/.local/bin. Adicione esse diretório ao PATH ou use CODAFORT_INSTALL=/usr/local/bin.

Agente (MCP)

O servidor não aparece no Claude Code / Cursor. Reinicie o agente depois do codafort mcp install e confira o arquivo que ele disse ter gravado (a tabela de caminhos por agente está em No agente). No escopo global, all pula o agente cuja pasta de configuração não existe; use --client <agente>. Se o agente abre pelo Dock ou pelo menu e não acha codafort, registre o caminho completo: codafort mcp install --command "$(command -v codafort)". codafort mcp install --dry-run mostra o que seria escrito. Em outros clientes, registre um servidor stdio com o comando codafort mcp.

O agente "consertou", o finding sumiu e eu não vi diff. fix_preview não grava nada: quem aplica a correção é o agente. Se o finding sumiu sem diff, o agente pode ter marcado uma supressão. Rode codafort scan . e codafort report para ver o estado real; supressões aparecem no laudo.

vet

**axes.skipped traz V1-ingested-diagnostics.** Não é erro. O V1 só roda com --ingest <arquivo> (o tsc/junit/lcov que o CI já produziu). Sem ele, o eixo é declarado como pulado, nunca como limpo.

**No CI, o vet foi pulado com ::warning "base não resolve".** O checkout é raso. Use actions/checkout@v4 com fetch-depth: 0 ou aponte vet-base. Com vet-enforce: true, base indisponível reprova em vez de pular.

Exit code 2. Erro de execução: o vet não chegou a um veredito. Rode com --json e leia a mensagem.

Declaração contra-assinada

**attest create recusa por licença.** Criar uma declaração contra-assinada exige o plano Verified ou Platform; verificar é grátis para qualquer pessoa. codafort license status mostra o tier.

**--evidence recusado: "não é coda-evidence/1".** Você passou o laudo inteiro (coda-iast/1, coda-dast/1, coda-vet/1) em vez da contribuição de evidência. Gere-a com codatrace evidence --report laudo.json, codaprobe evidence --report laudo.json ou codafort vet --evidence-out vet.json.

**--supersedes recusado: commit ou digest diferentes.** Sucessão vale para o mesmo scan com mais evidência. Scan diferente pede declaração nova; o erro diz qual campo divergiu.

**O /verify diz "navegador sem Ed25519".** A verificação no navegador exige Chrome 137+, Safari 17+ ou Firefox 129+. Ou use a CLI, que é grátis: codafort attest verify <token>.

**dirty: true no payload.** A árvore tinha mudanças não commitadas no momento do scan, então o commit declarado não descreve o código escaneado. Faça o commit e rode de novo.

codatrace

**Tudo unreached.** Confira primeiro:

  1. A linha codatrace: agente desligado no stderr da aplicação (política, socket ou jdwp).
  2. No Python, a aplicação envolvida por codatrace_agent.wsgi/asgi; sem isso o agente não vê as requisições.
  3. No laudo, socket_connections_cut_by_deadline acima de zero: aumente --timeout.
  4. CODATRACE_ROOT igual à raiz que o codafort analisou, porque o codatrace casa arquivo e linha exatos com o que o codafort apontou.

Se o básico estiver certo, sobram três causas: a rota não foi exercitada, o sink foi chamado com dado interno, ou o codatrace não observa aquela categoria em execução. Exercite mais a aplicação e confira codatrace coverage. unreached quer dizer "não medido", nunca "seguro".

**Node: import { execSync } não é observado.** O agente precisa carregar antes dos módulos da aplicação: node --import .codatrace/agents/node/codatrace_agent.mjs app.js. Mesmo assim, uma função exportada solta por um pacote ESM não é observada; um método em protótipo é.

JVM: sinks JDBC/servlet sem cobertura. Esses sinks só são observados com a classe concreta no classpath (o driver JDBC, a servlet-api). codatrace coverage lista o que ficou sem cobertura e o motivo.

codaprobe

Exit 3: alvo recusado pelo escopo. O escopo recusa tudo que não está autorizado de forma explícita. Confira o host canônico, a port explícita, o path_prefix (casa por segmento inteiro do caminho) e granted: true. codaprobe check-scope explica a decisão sem tocar a rede.

Exit 20 ao carregar o escopo. Há um campo desconhecido ou com grafia errada no arquivo de escopo. A mensagem nomeia o campo.

**verify-audit diz CONSISTENT, não INTACT.** Sem --report ou --expect-anchor, só a cadeia interna do log é conferida. Passe o laudo com --report (ou a âncora com --expect-anchor) para a verificação completa.

codacrash

Exit 20: dump inválido. O formato não foi reconhecido ou o arquivo está truncado. Formatos aceitos: Minidump, core ELF/Mach-O, HPROF, hs_err, heapsnapshot V8 e core CPython.

Core gerado sob emulação (Rosetta/QEMU) sem sentido. Sob emulação, o core registra o emulador, não o seu programa. Gere o core na arquitetura nativa.

Desempenho

Scan lento em repositório grande. engine analyze --incremental reanalisa só o que mudou (o cache fica em .codafort/cache.redb). No CI, guarde o diretório .codafort/ em cache entre execuções.

Ainda preciso de ajuda

Discussions para dúvidas · Issues para bugs · [email protected], em privado, para vulnerabilidade na própria codafort.