Troubleshooting¶

cs doctor --fix resolves most issues automatically. If it does not, check here.

Daemon Connection Issues¶

TUI shows stale data or does not refresh¶

The TUI runs the engine in-process — there is no daemon or socket. It opens from the last saved snapshot (~/.cloudslash/graph.snap) and refreshes in the background. If a scan seems stuck:

cs doctor            # environment + plugin health
cs tui               # fresh process
Ctrl+R in the TUI    # force a rescan

If the snapshot itself is corrupt, remove it and rescan:

rm ~/.cloudslash/graph.snap && cs scan

Horizon web UI shows a blank page¶

The browser console is Horizon SaaS, not a local server — there is nothing to start on your machine.

1. Confirm you are signed in at https://app.cloudslash.dev
2. Open the browser console (F12) and check for failed API requests
3. Verify the API host responds: curl -s https://api.cloudslash.dev/healthz

Cloud Provider Credentials¶

No credentials found¶

The source plugin could not read credentials from your environment. Each plugin documents its own credential chain and connection fields; follow that plugin's README or the connection form in Horizon. CloudSlash never stores your provider keys locally.

AI Provider Issues¶

AI Not Responding¶

1. Check your configuration: cs config get ai.provider
2. Verify the API key is set: cs config get ai.openai_key (or the appropriate key)
3. For Ollama, verify it's running: curl http://localhost:11434/api/tags
4. Re-run the config wizard: cs config

Wrong Model Selected¶

cs config set ai.model gpt-4o          # Set directly
cs config                               # Or use the interactive wizard

Rate Limited by AI Provider (429)¶

CloudSlash automatically retries with exponential backoff (up to 3 attempts). If you're hitting limits consistently, consider:

• Switching to Ollama for unlimited local inference
• Using a cheaper/faster model for routine queries
• The two-tier classifier routes ~80-90% of queries to the cheap model automatically

Plugin Issues¶

"no plugin registered for provider: "¶

The plugin is installed but not loaded. Check what is installed and active:

cs plugin list
cs doctor

Each source plugin owns its own credential and configuration contract; there is no global provider list. Follow the plugin README or the connection form in Horizon.

Plugin Binary "permission denied"¶

chmod +x ~/.cloudslash/plugins/<plugin>/<binary>

Plugin Checksum Mismatch¶

The plugin's binary hash doesn't match its manifest. This can happen after a manual file edit or corrupted download:

# Reinstall the plugin
cs plugin install <name> --force

Scan Issues¶

Scan Timeout in CI¶

The default timeout is 10 minutes. For large accounts, increase it:

cs scan --timeout=20m

SARIF Not Uploading to GitHub¶

Ensure your GitHub Actions workflow uses the correct action version:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: cloudslash

The category field prevents collisions with other SARIF producers (CodeQL, Semgrep).

Scan Returns Zero Results¶

1. Check that plugins are installed: cs plugin list
2. Check that plugins are activated in config
3. Verify credentials and permissions: cs doctor
4. Confirm target scope: inspect regions or namespaces specified in config.yaml

Data & Storage¶

BadgerDB Corruption¶

If the graph store becomes corrupted:

# Try auto-repair first
cs doctor --fix

# If that fails, delete and rebuild from next scan
rm -rf ~/.cloudslash/devi-graph/
cs scan    # Rebuilds the graph store

Disk Space¶

CloudSlash stores data at ~/.cloudslash/. To check sizes:

du -sh ~/.cloudslash/*/

To prune old event history:

# Via CLI
cs history prune --older-than 90d

# Via API
curl -X POST http://localhost:8080/api/v1/history/prune \
  -d '{"max_age_days": 90}'

OpenTelemetry¶

Traces Not Appearing¶

1. Verify the endpoint is reachable: curl http://your-otel-endpoint:4318/v1/traces
2. Check the flag: cs scan --otel-endpoint http://jaeger:4318
3. Ensure the daemon was restarted with the flag (it's not hot-reloadable)

Performance¶

Slow Scans on Large Accounts¶

• Use --region to scope scans to a specific region
• The AIMD concurrency controller automatically backs off on rate limits: this is expected
• Check scan diagnostics with cs scan --rules <file> and cs doctor

High Memory Usage¶

Large graphs (>100K nodes) may consume significant memory. Options:

• The BadgerDB temporal store automatically spills cold data to disk
• Scope scans to fewer providers or regions
• Consider running the daemon on a machine with more RAM for very large accounts

Getting More Help¶

cs doctor           # Run full system diagnostics
cs doctor --fix     # Auto-repair detected issues
cs status           # Quick health check

If the issue persists, check the daemon logs:

cs watch --interval 5m --alert-on-change    # continuous scanning with change alerts