Troubleshooting

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

Analysis Issues

”No files found”

→ Analyzing project...
  Found 0 matching source files

Causes:

• Wrong directory
• No supported language files
• Files excluded by ignore rules (like .gitignore)

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

Tip

If your source files exist but Unfault still finds 0 files, check whether they’re ignored. Unfault respects .gitignore (including global gitignore and .git/info/exclude), .ignore, and .dockerignore.

”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

LLM Issues

”LLM provider not configured”

The unfault review LLM summary feature requires a configured LLM provider. Configure one with:

# OpenAI
unfault config llm openai --model gpt-4o

# Anthropic
unfault config llm anthropic --model claude-3-5-sonnet-latest

# Ollama (local)
unfault config llm ollama --model llama3.2

Check current config:

unfault config show
unfault config llm show

“ANTHROPIC_API_KEY not set” / “OPENAI_API_KEY not set”

The LLM provider needs an API key. Set the relevant environment variable:

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="sk-..."

Or pass the key directly when configuring:

unfault config llm anthropic --api-key "..."

Observability Integration Issues

SLO data not appearing

If you expect SLO enrichment but it’s not showing:

1. Check integration credentials are present:

   unfault config integrations show

2. Verify connectivity:

   unfault config integrations verify

3. Run without --offline (if you were using it):

   unfault review  # Without --offline

4. If cache may be stale, refresh it:

   unfault review --refresh-cache

Credentials not detected

Unfault reads credentials from environment variables. Check the relevant provider:

Provider	Variables
GCP	Application Default Credentials via gcloud auth application-default login
Datadog	DD_API_KEY, DD_APP_KEY
Dynatrace	DT_API_TOKEN, DT_ENVIRONMENT_URL

Run unfault config integrations show to see what Unfault detects.

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, package.json, or .unfault.toml)
• 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

LSP / Editor Issues

No diagnostics appearing in editor

1. Check the language server output: run unfault lsp --verbose manually and look for errors.
2. Verify unfault is on your PATH and runs without errors.
3. Check that your project root has a recognizable manifest file (pyproject.toml, Cargo.toml, go.mod, package.json, etc.).

Slow first analysis in editor

The first run builds the full semantic graph for your project. Subsequent interactions use a cache and should be fast.

Verbose Mode

For detailed diagnostics:

unfault review -v

This shows:

• Which config files are loaded
• Workspace detection details
• Files found and ignored

Tip

When reporting issues, include the verbose output. It helps narrow down what’s happening.

Getting Help

Check your configuration

unfault config show

This shows your LLM and integration configuration.

Report an issue

If you’ve found a bug or unexpected behavior:

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

Quick Reference

Symptom	Likely Cause	First Step
”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 path
LLM not working	No provider configured	unfault config llm show
Rules not excluded	Path pattern mismatch	Check TOML syntax
SLO data missing	Missing credentials	unfault config integrations show