Troubleshooting¶

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

Daemon Connection Issues¶

"CRITICAL: Daemon Disconnected" in TUI¶

The TUI requires a running daemon to display live data.

# Start the daemon
cs daemon

# Or start in demo mode without cloud credentials
cs daemon --mock

If the daemon was already running, a stale socket may be blocking the connection:

cs doctor --fix    # Removes stale sockets and restarts the daemon

Web UI Shows Blank Page¶

1. Confirm the daemon is running: cs status
2. Check the port: the Web UI runs on 8080 by default.
3. Open browser console (F12) and check for errors
4. Ensure no other process is using port 8080: lsof -i :8080

Cloud Provider Credentials¶

AWS: "unable to locate credentials"¶

CloudSlash uses the standard AWS credential chain. Ensure one of these is configured:

# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 2: AWS CLI profile
aws configure

# Option 3: Specific profile
export AWS_PROFILE=production

Verify with: aws sts get-caller-identity

GCP: "could not find default credentials"¶

# Interactive login
gcloud auth application-default login

# Or set a service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Verify with: gcloud auth application-default print-access-token

Azure: "credential init failed"¶

# Interactive login
az login

# Or use service principal
export AZURE_CLIENT_ID=...
export AZURE_CLIENT_SECRET=...
export AZURE_TENANT_ID=...
export AZURE_SUBSCRIPTION_ID=...

Verify with: az account show

Kubernetes: "unable to load kubeconfig"¶

Ensure ~/.kube/config exists and points to a valid cluster:

kubectl cluster-info

No Credentials at All¶

CloudSlash degrades to mock mode automatically when no credentials are found. You'll see:

WARN: No cloud credentials found: falling back to mock mode for static analysis

This is expected in CI environments. No --mock flag is needed.

AI Provider Issues¶

AI Not Responding¶

1. Check your configuration with cs config view (look for ai.provider)
2. Verify the API key is set: cs config set ai.openai_key <key> (or the appropriate key for your provider)
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: aws"¶

The plugin binary is installed but not activated:

# Check installed plugins
cs plugin list

# Add to active plugins in config
cs config set plugins.active "aws,gcp"

Or add manually to ~/.cloudslash/config.yaml:

plugins:
  active:
    - aws
    - gcp

Plugin Binary "permission denied"¶

chmod +x ~/.cloudslash/plugins/cloudslash-plugin-aws

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 aws: 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 cloud credentials: cs doctor
4. Try mock mode to confirm the engine works: cs scan --mock

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 daemon --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 the Swarm debug output with cs daemon --verbose

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 daemon --verbose    # Run with debug logging (the daemon runs in the foreground by default)