Troubleshooting & Debugging

Diagnostic guides and solutions for common issues, errors, and debugging techniques in Soothe.

Canonical hub. The root troubleshooting.md is a redirect to this page. Content from the legacy root file has been merged here.

Guides

1. Debug Guide

Comprehensive debugging guide for agents and daemon
Log file locations, verbose output, and diagnostic strategies

Troubleshooting Guide

Solutions to common issues with Soothe.

API Key Issues

Error: Could not resolve model

Error: Could not resolve model openai:gpt-4o-mini

Solution: Set your OpenAI API key:

export OPENAI_API_KEY=sk-your-key-here

Or in .env file:

OPENAI_API_KEY=sk-your-key-here

Error: Invalid API key

Error: Invalid API key provided

Solution:

Verify the key is correct
Check for typos or extra spaces
Ensure the key has necessary permissions
Try regenerating the key from the provider dashboard

Subagent Issues

Optional soothe-plugins delegate not working

Optional delegated agents ship in soothe-plugins, not as soothe[…] extras. Install that package and follow its README for provider keys, extras, and subagents.* YAML.

Ensure matching subagents.<name>.enabled: true in your agent config for the delegate you enabled.

Subagent Disabled

Error: Subagent '<name>' is disabled

Solution: Enable in configuration:

subagents:
  <name>:
    enabled: true

WebSocket Connection Issues

Error: WebSocket connection failed

Error: WebSocket connection failed or Connection refused

Solution:

Check daemon status:
```
soothed status
```

Ensure WebSocket is enabled in ~/.soothe/config/daemon.yml:

transports:
  websocket:
 enabled: true
 host: "127.0.0.1"
 port: 8765

Restart daemon:
```
soothed stop
soothed start
```

Error: Connection timeout

Error: WebSocket connection timeout

Solution:

Check firewall settings
Verify host and port are correct
Ensure no other process is using the port

Authentication Errors

Error: Authentication failed

Error: 401 Unauthorized or Authentication required

Solution:

Soothe does not include built-in authentication. If you’re seeing auth errors, they’re coming from your reverse proxy.

Check reverse proxy configuration: Ensure API key/JWT validation is configured correctly
Verify credentials: Check that you’re sending the correct auth header
Check reverse proxy logs: Auth errors are logged by nginx/Caddy/Traefik, not Soothe

Example with nginx:

# Check nginx error logs
tail -f /var/log/nginx/error.log

# Verify API key in request
curl -H "X-API-Key: your-api-key" \
  https://soothe.example.com/ws

Example with Caddy:

# Check Caddy logs
journalctl -u caddy -f

# Verify JWT token
curl -H "Authorization: Bearer your-jwt-token" \
  https://soothe.example.com/ws

Error: CORS policy blocked

Error: CORS policy blocked in the client developer tools

Solution: This is handled by the reverse proxy, not Soothe directly.

nginx configuration:

location / {
    add_header Access-Control-Allow-Origin "https://your-app.example.com";
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
    add_header Access-Control-Allow-Headers "X-API-Key, Content-Type";

    if ($request_method = OPTIONS) {
        return 204;
    }

    proxy_pass http://localhost:8765;
}

Caddy configuration:

soothe.example.com {
    @websocket {
        header Connection *Upgrade*
        header Upgrade websocket
    }

    handle @websocket {
        reverse_proxy localhost:8765
    }
}

CORS Errors

Error: CORS policy blocked

Error: CORS policy blocked in the client developer tools

Solution: Add your origin to allowed CORS origins:

# ~/.soothe/config/daemon.yml
transports:
  websocket:
    enabled: true
    cors_origins:
      - "http://localhost:*"
      - "http://127.0.0.1:*"
      - "http://myapp.example.com"  # Your origin

Restart daemon after updating:

soothed stop
soothed start

Daemon Issues

Error: Address already in use

Error: Address already in use: 127.0.0.1:8765

Solution: Port 8765 is in use by a previous daemon instance

soothed stop
soothed start

Error: Daemon won’t start

Error: Daemon exits immediately

Solution:

Check logs:
```
tail -f ~/.soothe/logs/soothed.log
```
Enable debug mode:
```
export SOOTHE_DEBUG=true
soothed start
```

Verify configuration file syntax:

python -c "import yaml; yaml.safe_load(open('~/.soothe/config/config.yml'.replace('~', '$HOME')))"

Error: Daemon not responding

Error: Commands hang or timeout

Solution:

Check daemon status:
```
soothed status
```
Restart daemon:
```
soothed stop
soothed start
```

Check for zombie processes:

ps aux | grep soothe
kill -9 <pid>  # If needed

Error: `Request exceeded … timeout` / step cancelled after ~14 days

Symptoms: Daemon log shows request timeout (1209600s) or RuntimeError: Request exceeded 1209600s timeout; step marked cancelled; goal did not complete.

Cause: The turn exceeded thread_pool.request_timeout_seconds (default 14 days). Autopilot dispatches use the parallel agent.autopilot.goal_deadline_seconds knob (same default).

Solution:

Continue the loop if checkpoint state is good: soothe loop continue <loop_id>

Raise or disable the cap in ~/.soothe/config/daemon.yml:

thread_pool:
  request_timeout_seconds: 0  # no timeout

For autopilot-only workloads, adjust agent.autopilot.goal_deadline_seconds in config.yml (null disables).
Restart daemon after config changes: soothed stop && soothed start

See Production Setup — Request timeouts.

Thread Issues

Error: Thread not found

Error: Thread abc123 not found

Solution:

List available threads:
```
soothe loop list
```
Check thread ID spelling
Verify thread hasn’t been deleted

Error: Thread corrupted

Error: Failed to load thread

Solution:

Export thread data if possible:
```
soothe loop show abc123
```
Delete and recreate:
```
soothe loop delete abc123
```

Vector Store Issues

Error: Connection refused (PostgreSQL)

Error: Connection refused for pgvector

Solution:

Start infrastructure (development stack):

docker compose -f docker-compose.yml up -d

Configure connection:

vector_store_provider: pgvector
vector_store_config:
  dsn: "postgresql://postgres:postgres@localhost:5432/vectordb"

Error: Collection not found

Error: Collection 'soothe_skillify' not found

Solution: Collections are created automatically on first use. Ensure the vector store is running and accessible.

Model Resolution Issues

Error: Provider not found

Error: Provider 'openai' not found

Solution: Ensure provider name matches:

providers:
  - name: openai  # Must match router reference
    provider_type: openai
    api_key: "${OPENAI_API_KEY}"

router:
  default: "openai:gpt-4o-mini"  # "openai" matches provider name

Error: Model not found

Error: Model 'gpt-4o-mini' not available

Solution: Add model to provider list:

providers:
  - name: openai
    models:
      - gpt-4o-mini  # Add here
      - gpt-4o

Performance Issues

Slow Response Times

Solution:

Check network latency
Use smaller model for simple tasks:
```
router:
  fast: "openai:gpt-4o-mini"
```
Stabilize the cacheable prefix (RFC-214): keep workspace blocks and tool schemas stable across hops; enable progressive_tools and cap workspace_instructions_max_chars in config.yml. Provider-specific cache APIs are not configured via a single YAML flag.

High Memory Usage

Solution:

Reduce context size:
```
context:
  max_tokens: 8000
```
Archive old threads:
```
soothe loop prune abc123 --dry-run
```
Restart daemon periodically

Debug Mode

For comprehensive debugging instructions, see the Debug Guide.

Enable verbose logging to diagnose issues:

export SOOTHE_DEBUG=true
soothe

For daemon-specific logging:

export SOOTHE_DEBUG=true
soothed start

Or in YAML:

debug: true

Key Debug Features

The debug guide covers:

Log locations: ~/.soothe/logs/, ~/.soothe/runs/
Enable debug logs: Environment variables and config files
Monitor logs in real-time: tail -f commands for daemon, CLI, and thread logs
LLM tracing: Debug model behavior with request/response logging
Verbosity levels: Understand TUI event filtering (quiet/normal/debug)
Common workflows: Debug agent behavior, LLM issues, connection, subagents, protocols
Performance profiling: Analyze agent performance from logs

Getting Help

Use /help in the TUI to see available commands
Check the Debug Guide for comprehensive debugging instructions
Check logs: ~/.soothe/logs/soothed.log, ~/.soothe/logs/soothe.log, ~/.soothe/logs/soothe-cli.log
Review configuration: check ~/.soothe/config/config.yml
Check the documentation for detailed guides
Review RFCs and implementation guides in docs/specs/ and docs/impl/

Debug Guide - Enable debug logs, diagnose issues, log locations
Configuration Guide - Configuration reference
Daemon Management - Daemon lifecycle
Multi-Transport Setup - Transport configuration
Authentication - Auth setup

Debug Guide

Troubleshooting & Debugging

Guides

1. Debug Guide

Troubleshooting Guide

API Key Issues

Error: Could not resolve model

Error: Invalid API key

Subagent Issues

Optional soothe-plugins delegate not working

Subagent Disabled

WebSocket Connection Issues

Error: WebSocket connection failed

Error: Connection timeout

Authentication Errors

Error: Authentication failed

Error: CORS policy blocked

CORS Errors

Error: CORS policy blocked

Daemon Issues

Error: Address already in use

Error: Daemon won’t start

Error: Daemon not responding

Error: Request exceeded … timeout / step cancelled after ~14 days

Thread Issues

Error: Thread not found

Error: Thread corrupted

Vector Store Issues

Error: Connection refused (PostgreSQL)

Error: Collection not found

Model Resolution Issues

Error: Provider not found

Error: Model not found

Performance Issues

Slow Response Times

High Memory Usage

Debug Mode

Key Debug Features

Getting Help

Related Guides

Table of contents

Error: `Request exceeded … timeout` / step cancelled after ~14 days