Troubleshooting

Common issues and how to resolve them.

No Findings Reported

Symptom: bouncerfox scan . exits with code 0 and shows no output.

Causes:

1. No governed files found. BouncerFox only scans recognized file types (see What is BouncerFox?). Run bouncerfox scan . --verbose to see which files were scanned.
2. Files are ignored. Check your .bouncerfox.yml for ignore patterns that may exclude the files you expect to be scanned.
3. Severity floor is too high. If severity_floor is set to high or critical, lower-severity findings are filtered out. Try bouncerfox scan . --severity info to see everything.
4. Profile disables relevant rules. The recommended profile disables some informational rules. Try profile: all_rules in your config to enable every rule.

Too Many Findings

Symptom: The scan reports many findings that are not relevant to your project.

Solutions:

1. Add an allowlist for SEC_002. If external URLs are expected, add trusted domains to the allowlist:

   rules:
     SEC_002:
       params:
         url_allowlist:
           - "https://api.yourcompany.com"

2. Disable specific rules. Turn off rules that don't apply:

   rules:
     QA_001:
       enabled: false

3. Ignore directories. Exclude vendor or generated files:

   ignore:
     - "vendor/**"
     - "**/*.generated.md"

"warning: rules version mismatch"

Symptom: warning: rules version mismatch: local=X platform=Y

The platform expects a different version of the built-in rules than your CLI has. This usually means your CLI is outdated.

Fix: Update BouncerFox to the latest version:

brew upgrade bouncerfox
# or
go install github.com/bouncerfox/cli/cmd/bouncerfox@latest

"warning: config pull failed"

Symptom: warning: config pull failed: ... (using local config)

The CLI could not reach the platform API. It falls back to local config.

Causes:

• Network connectivity issue
• BOUNCERFOX_PLATFORM_URL is set to an incorrect URL
• Platform is temporarily unavailable

Fix: Check your network. Verify BOUNCERFOX_PLATFORM_URL if set. The scan continues with local config.

"error: platform unreachable" (exit code 2)

Symptom: The scan exits with code 2 and error: platform unreachable.

In CI, the default offline behavior is fail-closed. When the platform cannot be reached, the scan fails rather than producing a verdict without platform enforcement.

Fix: To fall back to local exit logic instead:

bouncerfox scan . --offline-behavior warn

Or set it in your CI workflow:

- uses: bouncerfox/cli@v0
  env:
    BOUNCERFOX_API_KEY: ${{ secrets.BOUNCERFOX_API_KEY }}
  with:
    path: .

"warning: skipping ... resolves outside scan root"

Symptom: warning: skipping path/to/file: resolves outside scan root

A symlink in the scan directory points to a file outside the project root. BouncerFox rejects these for security (prevents path traversal).

Fix: Remove the symlink or copy the target file into the project directory.

"warning: file limit reached"

Symptom: warning: file limit (500) reached; stopping scan

The project contains more than 500 governed files. BouncerFox stops scanning to prevent resource exhaustion.

Fix: Use ignore patterns in .bouncerfox.yml to exclude directories that don't need scanning:

ignore:
  - "node_modules/**"
  - "vendor/**"
  - "test/fixtures/**"

"warning: scan timed out"

Symptom: warning: scan timed out after 5m0s

The scan exceeded the 5-minute timeout. This typically happens with very large projects.

Fix: Narrow the scan scope by ignoring directories that don't contain agent config files, or scan specific paths instead of the entire project:

bouncerfox scan CLAUDE.md .claude/ .mcp.json

GitHub Action: "--github-comment requires GITHUB_TOKEN"

Symptom: warning: --github-comment requires GITHUB_TOKEN env var

The --github-comment flag needs a GitHub token to post PR comments and check runs.

Fix: Add the token to your workflow:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note: In connected mode (BOUNCERFOX_API_KEY set), the platform handles GitHub feedback. You don't need GITHUB_TOKEN or --github-comment.

Custom Rule Compilation Errors

Symptom: warning: could not compile custom rule CUSTOM_001: ...

A custom rule in your config has a syntax error. The rule is skipped but the scan continues.

Common causes:

• Invalid regex pattern (must be RE2 compatible, no lookaheads)
• Unknown match type
• Missing required fields (id, name, match)
• Regex exceeds 4096 character limit

Fix: Check your custom rule definition against the custom rules guide.

Still Stuck?

• Run with --verbose for more detail on what the scanner is doing
• Check GitHub Issues for known problems
• Open a new issue with your BouncerFox version (bouncerfox version), OS, and the error output