Troubleshooting

Troubleshooting

Start with the framework's built-in diagnostics:

osint --version
osint forge validate
osint forge doctor

Command not found

Confirm /usr/local/bin is on PATH and rerun ./bootstrap.sh from the intended stable source tree. pipx-installed commands may live in ~/.local/bin; OSINT Forge searches the standard per-user pipx location.

Plugin unavailable or unhealthy

osint forge info TOOL
osint forge install TOOL --dry-run
osint forge doctor TOOL

A successful install script does not guarantee an upstream command is healthy. Doctor propagates failed self-checks. Review credentials, interactive setup, and upstream service requirements.

Manifest validation failure

Run osint forge validate --json for structured errors. Common causes include an ID/directory mismatch, invalid version or tags, missing executable lifecycle scripts, path escape, unsupported target type, missing adapter, or shell-string interpolation.

Batch problems

• A target before a recognized section is invalid.
• Unknown plugin filters are rejected.
• Only installed, compatible, batch-capable plugins run.
• Use --dry-run to inspect the job plan.
• Each run receives a distinct directory; inspect its summary and logs.

Case problems

• Case IDs allow letters, numbers, dots, underscores, and hyphens and cannot traverse directories.
• Purpose and authorization cannot be empty.
• Unknown cases, malformed metadata, symlinks, and unsupported future schemas are rejected.
• Failed or interrupted jobs remain resumable; rerun the same case command.
• Use --rerun only when successful jobs should execute again.
• Custom report files require --force to replace and cannot overwrite reserved case artifacts.
• Use osint case findings CASE --json to inspect normalized findings and osint case entities CASE --json to inspect canonical seeds and extracted candidates.
• Completed jobs with missing, malformed, oversized, unsafe, or out-of-bound normalized output produce visible normalization errors and a nonzero report exit.
• Shareable reports are conservative structure-only exports and still require human review.

Autonomous QA problems

Use ./scripts/codex-qa.sh status for a concise checkpoint and ./scripts/codex-qa.sh attach for the live session; detach with Ctrl-b d. A stopped session with exit code 0 is not sufficient by itself—read final-result.md and require an exact-commit PASS. Preserve failed or misleading supplemental audits and rerun them with fail-fast shell settings rather than reinterpreting them.

Permission problems

Case and batch artifacts should be private to the owner. Parent directories, backups, copied exports, and upstream-created files remain the user's responsibility.

Reporting defects

Use synthetic data, remove secrets and targets from logs, and open a normal issue for ordinary bugs. Report suspected vulnerabilities privately through the canonical security policy.