Problemas comunes

Síntomas comunes, su causa y qué hacer. Falso positivo, falso negativo y crash son bugs: abre un issue.

Instalación

**El enlace de descarga da 404 / install.sh no encuentra release.** Prelanzamiento: todavía no se publicó ningún release. Los canales entran en línea en la v0.1.0, y las instrucciones ya son las definitivas.

**minisign: not found en install.sh.** El script verifica el SHA-256 siempre y la firma minisign solo si minisign está instalado. Instálalo (brew install minisign / apt install minisign) para la verificación completa. Ver Cadena de suministro.

**codafort: command not found después del script.** El script instala en ~/.local/bin. Agrega ese directorio al PATH o usa CODAFORT_INSTALL=/usr/local/bin.

Agente (MCP)

El servidor no aparece en Claude Code / Cursor. Reinicia el agente después de codafort mcp install y revisa el archivo que dijo haber grabado (la tabla de rutas por agente está en En el agente). En el alcance global, all omite el agente cuya carpeta de configuración no existe; usa --client <agente>. Si el agente se abre desde el Dock o un menú y no encuentra codafort, registra la ruta completa: codafort mcp install --command "$(command -v codafort)". codafort mcp install --dry-run muestra lo que se escribiría. En otros clientes, registra un servidor stdio con el comando codafort mcp.

El agente "corrigió", el finding desapareció y no vi diff. fix_preview no escribe nada: quien aplica la corrección es el agente. Si el finding desapareció sin diff, el agente puede haber marcado una supresión. Ejecuta codafort scan . y codafort report para ver el estado real; las supresiones aparecen en el informe.

vet

**axes.skipped trae V1-ingested-diagnostics.** No es un error. V1 solo corre con --ingest <archivo> (el tsc/junit/lcov que el CI ya produjo). Sin él, el eje se declara omitido, nunca limpio.

**En el CI, vet se omitió con ::warning "la base no resuelve".** El checkout es superficial. Usa actions/checkout@v4 con fetch-depth: 0 o apunta vet-base. Con vet-enforce: true, una base indisponible reprueba en vez de omitirse.

Exit code 2. Error de ejecución: vet no llegó a un veredicto. Corre con --json y lee el mensaje.

Declaración contrafirmada

**attest create rechaza por licencia.** Crear una declaración contrafirmada requiere el plan Verified o Platform; verificar es gratis para cualquiera. codafort license status muestra el tier.

**--evidence rechazado: "no es coda-evidence/1".** Pasaste el informe entero (coda-iast/1, coda-dast/1, coda-vet/1) en vez de la contribución de evidencia. Genérala con codatrace evidence --report informe.json, codaprobe evidence --report informe.json o codafort vet --evidence-out vet.json.

**--supersedes rechazado: commit o digest distintos.** La sucesión vale para el mismo scan con más evidencia. Un scan distinto pide una declaración nueva; el error nombra el campo que divergió.

**/verify dice "navegador sin Ed25519".** La verificación en el navegador exige Chrome 137+, Safari 17+ o Firefox 129+. O usa la CLI, que es gratis: codafort attest verify <token>.

**dirty: true en el payload.** El árbol tenía cambios sin commit en el momento del scan, así que el commit declarado no describe el código escaneado. Haz commit y vuelve a correr.

codatrace

**Todo unreached.** Revisa primero:

  1. La línea codatrace: agente desligado en el stderr de la aplicación (política, socket o jdwp).
  2. En Python, la aplicación envuelta por codatrace_agent.wsgi/asgi; sin eso el agente no ve los requests.
  3. En el informe, socket_connections_cut_by_deadline mayor que cero: sube --timeout.
  4. CODATRACE_ROOT igual a la raíz que codafort analizó, porque codatrace casa el archivo y la línea exactos que codafort señaló.

Si lo básico está bien, quedan tres causas: la ruta no fue ejercitada, el sink fue llamado con dato interno, o codatrace no observa esa categoría en ejecución. Ejercita más la aplicación y revisa codatrace coverage. unreached quiere decir "no medido", nunca "seguro".

**Node: import { execSync } no se observa.** El agente debe cargar antes de los módulos de la aplicación: node --import .codatrace/agents/node/codatrace_agent.mjs app.js. Aun así, una función exportada suelta de un paquete ESM no se observa; un método de prototipo sí.

JVM: sinks JDBC/servlet sin cobertura. Esos sinks solo se observan con la clase concreta en el classpath (el driver JDBC, la servlet-api). codatrace coverage lista lo que quedó sin cobertura y el motivo.

codaprobe

Exit 3: objetivo rechazado por el alcance. El alcance rechaza todo lo que no está autorizado de forma explícita. Revisa el host canónico, el port explícito, el path_prefix (casa por segmento entero de la ruta) y granted: true. codaprobe check-scope explica la decisión sin tocar la red.

Exit 20 al cargar el alcance. El archivo de alcance tiene un campo desconocido o mal escrito. El mensaje nombra el campo.

**verify-audit dice CONSISTENT, no INTACT.** Sin --report o --expect-anchor, solo se verifica la cadena interna del log. Pasa el informe con --report (o el ancla con --expect-anchor) para la verificación completa.

codacrash

Exit 20: dump inválido. El formato no se reconoció o el archivo está truncado. Formatos aceptados: Minidump, core ELF/Mach-O, HPROF, hs_err, heapsnapshot V8 y core CPython.

Core generado bajo emulación (Rosetta/QEMU) sin sentido. Bajo emulación, el core registra el emulador, no tu programa. Genera el core en la arquitectura nativa.

Rendimiento

Scan lento en un repositorio grande. engine analyze --incremental reanaliza solo lo que cambió (la caché queda en .codafort/cache.redb). En CI, cachea el directorio .codafort/ entre ejecuciones.

Todavía necesito ayuda

Discussions para dudas · Issues para bugs · [email protected], en privado, para una vulnerabilidad en la propia codafort.