Troubleshooting

Common Fossa CLI errors, exit codes, and how to debug them.

Start any investigation with:

fossa status
fossa auth status
fossa review --verbose    # or any command with --verbose

fossa status shows the consolidated state (auth mode, org, repo, hook, version). --verbose prints the resolved API URL and per-request details.

Common Errors

Command not found: fossa

The CLI isn’t on your PATH. Reinstall with your package manager’s global flag, or use npx @fossa/cli <command> for one-off runs.

• npm install -g @fossa/cli
• yarn global add @fossa/cli
• pnpm add -g @fossa/cli
• bun add -g @fossa/cli

If you installed via the skill installer, re-run curl -fsSL https://review-skill.com/install | bash to fix PATH entries.

AUTH_REQUIRED or 401 Unauthorized

• Run fossa auth status to see the current mode.
• If using a team key, verify it’s still active at app.fossa.local/organization/cli-keys.
• If using personal login, try fossa auth login again — the refresh token may have expired.
• For CI, confirm FOSSA_TOKEN (or FOSSA_TEAM_KEY) is set in the environment the pipeline runs in.
• If self-hosted, confirm FOSSA_API_URL points to the correct instance.

NOT_IN_GIT_REPO

fossa review requires a git working directory. cd into a repo or initialize one with git init. For fossa config repo commands, you can pass owner/repo explicitly instead of ..

Review takes very long or seems to hang

Large branches (hundreds of files, thousands of lines) can take several minutes. The default request timeout is 60 minutes — you should see progress in verbose mode.

• Use --verbose to confirm the request is in flight.
• For very large diffs, prefer --branch <base> or --commit <sha> over working-tree mode: these let the backend clone the same commit instead of receiving inlined file contents.
• Override the timeout with FOSSA_REQUEST_TIMEOUT_MIN=90 fossa review if needed.
• Split work across smaller branches when practical.

Files are being skipped from the review

Review honors the ignore-files patterns configured in fossa config repo. List current settings with:

fossa config repo show

You can add or remove patterns:

fossa config repo add-ignore-file . "**/*.generated.ts"
fossa config repo remove-ignore-file . "**/*.generated.ts"

Binary files, images, and lockfiles are skipped by default.

Rate limit reached / Trial exhausted

Trial mode allows 5 reviews per day. Sign in with fossa auth login or configure a team key via fossa auth team-key --key fossa_xxxxx to raise limits. fossa auth status prints your current usage.

API returned invalid response (expected JSON, got HTML)

Your FOSSA_API_URL is hitting a reverse proxy or Cloudflare Access page instead of the API. Check:

• The URL path (no stray /api, /v1, etc.).
• Cloudflare Access credentials (CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET) if applicable.
• That the proxy forwards Authorization and CF-Access-* headers intact.

HTTPS required for API URL

The CLI rejects non-HTTPS API URLs for everything except localhost and 127.0.0.1. Provision a valid TLS certificate for your self-hosted instance, or use http://localhost:<port> for local development.

Pre-push hook is not running

• Confirm installation: fossa hook status.
• Make sure .git/hooks/pre-push is executable.
• Other hook managers (Husky, Lefthook, pre-commit) may overwrite .git/hooks/pre-push. Either chain them or reinstall with fossa hook install --force.
• Skip the hook for a single push: FOSSA_SKIP_HOOK=1 git push.

Device limit reached

Self-hosted instances can enforce device limits per organization. Ask your admin to increase the limit or remove unused devices from the dashboard.

Exit Codes

Use these in scripts and CI pipelines.

Code	Meaning
0	Success. No issues found, or issues were found but below --fail-on.
1	Issues found at or above the --fail-on severity.
2	CLI usage error (invalid flag, missing argument).
3	Authentication or authorization failure.
4	Network or API error (timeout, 5xx, invalid response).
5	Not in a git repository, or no changes to review.

For CI, pair --fail-on error with --format json and --output review.json to surface structured results as pipeline artifacts without affecting the exit code logic.

Debugging Tips

• --verbose on any command prints the resolved API URL, request IDs, and timings.
• fossa schema outputs the machine-readable command schema — useful when your agent reports a missing flag.
• --agent enforces deterministic, machine-readable output; combine with --format json when scripting.
• FOSSA_VERBOSE=true persists verbose mode across multiple commands in a session.

Getting Help

• Report bugs: github.com/brittytino/fossa/issues
• Feature requests, configuration questions: your Fossa account manager, or [e-mail].
• For self-hosted deployments, include fossa status --verbose output when filing an issue.