Troubleshooting

Common symptoms, their cause and what to do. False positives, false negatives and crashes are bugs: open an issue.

Install

**The download link 404s / install.sh finds no release.** Pre-launch: no release has been published yet. The channels go live at v0.1.0, and the instructions are already the final ones.

**minisign: not found in install.sh.** The script always checks SHA-256 and checks the minisign signature only when minisign is installed. Install it (brew install minisign / apt install minisign) for the full verification. See Supply chain.

**codafort: command not found after the script.** The script installs into ~/.local/bin. Add that directory to PATH or use CODAFORT_INSTALL=/usr/local/bin.

Agent (MCP)

The server does not show up in Claude Code / Cursor. Restart the agent after codafort mcp install and check the file it said it wrote (the per-agent path table is in In the agent). In the global scope, all skips an agent whose config folder doesn't exist; use --client <agent>. If the agent is launched from the Dock or a menu and can't find codafort, register the full path: codafort mcp install --command "$(command -v codafort)". codafort mcp install --dry-run shows what would be written. In other clients, register a stdio server with the command codafort mcp.

The agent "fixed" it, the finding disappeared and I saw no diff. fix_preview writes nothing: the agent applies the fix. If the finding vanished without a diff, the agent may have marked a suppression. Run codafort scan . and codafort report for the real state; suppressions show in the report.

vet

**axes.skipped contains V1-ingested-diagnostics.** Not an error. V1 only runs with --ingest <file> (the tsc/junit/lcov output CI already produced). Without it the axis is declared skipped, never clean.

**In CI, vet was skipped with a ::warning "base does not resolve".** The checkout is shallow. Use actions/checkout@v4 with fetch-depth: 0 or set vet-base. With vet-enforce: true, an unavailable base fails instead of skipping.

Exit code 2. Execution error: vet did not reach a verdict. Run with --json and read the message.

Counter-signed declaration

**attest create refuses because of the licence.** Creating a counter-signed declaration requires the Verified or Platform plan; verifying is free for anyone. codafort license status shows the tier.

**--evidence refused: "not coda-evidence/1".** You passed the whole report (coda-iast/1, coda-dast/1, coda-vet/1) instead of the evidence contribution. Generate it with codatrace evidence --report report.json, codaprobe evidence --report report.json or codafort vet --evidence-out vet.json.

**--supersedes refused: different commit or digest.** Succession applies to the same scan with more evidence. A different scan needs a new declaration; the error names the diverging field.

**/verify says "browser lacks Ed25519".** Verifying in the browser needs Chrome 137+, Safari 17+ or Firefox 129+. Or use the CLI, which is free: codafort attest verify <token>.

**dirty: true in the payload.** The tree had uncommitted changes at scan time, so the declared commit does not describe the scanned code. Commit and run again.

codatrace

**Everything unreached.** Check first:

  1. The codatrace: agente desligado line on the application's stderr (policy, socket or jdwp).
  2. In Python, the application wrapped by codatrace_agent.wsgi/asgi; without it the agent does not see requests.
  3. In the report, socket_connections_cut_by_deadline above zero: raise --timeout.
  4. CODATRACE_ROOT equal to the root codafort analysed, because codatrace matches the exact file and line that codafort reported.

If the basics are right, three causes remain: the route was not exercised, the sink was called with internal data, or codatrace does not observe that category at runtime. Exercise the application more and check codatrace coverage. unreached means "not measured", never "safe".

**Node: import { execSync } is not observed.** The agent must load before the application's modules: node --import .codatrace/agents/node/codatrace_agent.mjs app.js. Even so, a loose function exported by an ESM package is not observed; a prototype method is.

JVM: JDBC/servlet sinks with no coverage. These sinks are only observed with the concrete class on the classpath (the JDBC driver, servlet-api). codatrace coverage lists what has no coverage and why.

codaprobe

Exit 3: target refused by scope. The scope refuses anything not explicitly authorized. Check the canonical host, an explicit port, the path_prefix (it matches whole path segments) and granted: true. codaprobe check-scope explains the decision without touching the network.

Exit 20 while loading the scope. The scope file has an unknown or misspelled field. The message names the field.

**verify-audit says CONSISTENT, not INTACT.** Without --report or --expect-anchor, only the log's internal chain is checked. Pass the report with --report (or the anchor with --expect-anchor) for the full verification.

codacrash

Exit 20: invalid dump. The format was not recognised or the file is truncated. Accepted formats: Minidump, ELF/Mach-O core, HPROF, hs_err, V8 heapsnapshot and CPython core.

A core produced under emulation (Rosetta/QEMU) makes no sense. Under emulation, the core records the emulator, not your program. Produce the core on the native architecture.

Performance

Slow scan on a large repository. engine analyze --incremental re-analyses only what changed (the cache lives in .codafort/cache.redb). In CI, cache the .codafort/ directory between runs.

Still need help

Discussions for questions · Issues for bugs · security@codafort.com, privately, for a vulnerability in codafort itself.