Troubleshooting

When something doesn’t work as expected, this guide helps you figure out why.

Authentication Issues

”Authentication required”

Error: Authentication required. Run 'unfault login' to authenticate.

Solution: Run the login flow:

unfault login

This opens a browser for device authentication. If you’re in CI/CD, use an API key instead:

export UNFAULT_API_KEY="sk_live_..."
unfault review

“Invalid or expired token”

Error: Invalid or expired token. Please re-authenticate.

Solution: Your session has expired. Log in again:

unfault login

Login flow doesn’t open browser

On headless systems or remote servers, the browser won’t open automatically.

Solution: Copy the URL shown in the terminal and open it manually:

To authenticate, visit: https://app.unfault.dev/auth/device/
Enter code: ABCD-1234

Analysis Issues

”No files found”

→ Analyzing project...
  Found 0 matching source files

Causes:

• Wrong directory
• No supported language files
• Files excluded by gitignore or config

Solutions:

Check you’re in the right place:

ls -la  # Should see your source files

Check supported extensions exist:

find . -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.ts" | head

Use verbose mode for more details:

unfault review -v

“Unknown language” or “Unsupported framework”

Unfault supports Python, Go, Rust, and TypeScript. If you’re using a different language, analysis won’t run.

For supported languages with unrecognized frameworks, analysis still works but framework-specific rules won’t apply.

Analysis is slow

Large codebases take time, but if analysis seems stuck:

Check for symlink loops:

find . -type l -exec test -e {} \; -print

Narrow the scope by running from a subdirectory:

# Instead of the whole repo
cd src
unfault review

Use verbose mode to see progress:

unfault review -v

Different results locally vs CI

Common causes:

1. Different working directories

   Make sure you’re running from the same directory in both environments.

2. Different git state

   # CI might have uncommitted changes excluded
   git status

3. Configuration differences

   Check which config is loaded with verbose mode:

   unfault review -v

Output Issues

JSON output is malformed

If JSON output appears truncated or malformed:

# Ensure nothing else writes to stdout
unfault review --output json 2>/dev/null > results.json

“Finding not actionable”

If a finding doesn’t make sense for your code:

1. Check if it’s a false positive specific to your pattern
2. Use inline suppression with a comment explaining why:

   # unfault: ignore[rule.id] -- reason this doesn't apply

3. Report it if you think it’s a bug in the rule

Connection Issues

”Connection refused” or “Network error”

Error: Failed to connect to API: Connection refused

Solutions:

Check your network:

curl -I https://api.unfault.dev/health

Check for proxy issues:

# If behind a corporate proxy
export HTTPS_PROXY="http://proxy.company.com:8080"
unfault review

“Timeout” errors

Error: Request timed out

Large codebases may hit default timeouts.

Solutions:

Analyze a smaller scope by running from a subdirectory:

cd src/api
unfault review

SSL certificate errors

Error: SSL certificate problem

Usually indicates a corporate proxy intercepting HTTPS.

Solution: Add the corporate CA certificate to your system trust store, or contact your IT department for guidance.

Configuration Issues

”Config not found” or wrong config loaded

Use verbose mode to see which config Unfault is loading:

unfault review -v

Common issues:

• Config is in wrong file (should be pyproject.toml, Cargo.toml, or package.json)
• TOML/JSON syntax errors in config
• Config key is misspelled

Validate your config:

# For TOML
python -c "import tomllib; tomllib.load(open('pyproject.toml', 'rb'))"

# For JSON
python -c "import json; json.load(open('package.json'))"

Rules not being excluded

If rules you’ve excluded still appear:

1. Check the path pattern matches:

   # This excludes the rule everywhere
   exclude = ["python.http.missing_timeout"]
   
   # This excludes it only in tests/
   exclude = ["python.http.missing_timeout:tests/*"]

2. Check for typos in rule IDs by looking at the finding output

Verbose Mode

For detailed diagnostics, use verbose mode:

unfault review -v

This shows:

• Which config files are loaded
• Workspace detection details
• API request/response details

Tip

When reporting issues, include the verbose output. It helps us understand what’s happening.

Getting Help

Check the status

unfault status

This shows your authentication status and configuration.

Report an issue

If you’ve found a bug or unexpected behavior:

1. Check existing issues: github.com/unfault/cli/issues
2. If new, open an issue with:
   • Unfault version (unfault --version)
   • OS and architecture
   • Verbose output (unfault review -v)
   • Minimal reproduction steps

Community

• GitHub Discussions: github.com/unfault/cli/discussions
• For security issues, email security@unfault.dev

Quick Reference

Symptom	Likely Cause	First Step
”Authentication required”	Not logged in	unfault login
”No files found”	Wrong directory	Check ls and pwd
Slow analysis	Large codebase	Run from subdirectory
Different results in CI	Different working directory	Ensure same cd path
Connection errors	Network/proxy issues	curl https://api.unfault.dev/health
Rules not excluded	Path pattern mismatch	Check TOML syntax