Troubleshooting

This guide covers common issues and their solutions.

Quick Diagnostics

Run the built-in diagnostic tool:

whisp doctor

This checks:

Daemon status
Socket connectivity
Configuration validity
API key configuration
Required dependencies

Daemon Issues

Daemon Won't Start

Symptoms: whisp start hangs or fails silently

Solutions:

Check for existing process:
```
pgrep -f "whisp.*daemon"
```
If a process exists, kill it: pkill -f "whisp.*daemon"
Remove stale PID file:
```
rm /tmp/whisp.pid
```
Remove stale socket:
```
rm /tmp/whisp.sock
```
Try foreground mode for debugging:
```
whisp start -f
```
This shows error messages directly in your terminal.

Daemon Keeps Dying

Symptoms: Daemon starts but stops unexpectedly

Solutions:

Check logs (if using systemd):
```
journalctl --user -u whisp -f
```
Verify API key is valid:
```
whisp doctor
```
Check available memory:
```
free -h
```

Stale Socket/PID

Symptoms: "Daemon already running" but it's not responding

Solution:

rm /tmp/whisp.sock /tmp/whisp.pid
whisp start

Connection Issues

"Daemon not running" Error

Symptoms: Commands show "Daemon not running. Start with: whisp start"

Solutions:

Start the daemon:
```
whisp start
```
Check socket path:
```
ls -la /tmp/whisp.sock
```
Verify socket environment variable:
```
echo $WHISP_SOCKET
```
Should be empty (uses default) or /tmp/whisp.sock

Socket Permission Denied

Symptoms: Can't connect to socket despite daemon running

Solutions:

Check socket permissions:
```
ls -la /tmp/whisp.sock
```
Should be owned by your user.
Restart daemon:
```
whisp restart
```

Timeout Errors

Symptoms: Commands hang then timeout

Solutions:

Check network connectivity (for cloud providers)
Try a different provider temporarily:
```
whisp config set provider ollama
```
Check daemon health:
```
whisp health
```

Provider Issues

API Key Errors

Symptoms: "Invalid API key" or authentication errors

Solutions:

Verify key is set:
```
whisp doctor
```
Re-run setup:
```
whisp init
```

Check environment variable:

# For OpenAI
echo $OPENAI_API_KEY

# For Anthropic
echo $ANTHROPIC_API_KEY

Verify key in config file:

cat ~/.config/whisp/config.toml | grep api_key

Rate Limit Errors

Symptoms: "Rate limit exceeded" or 429 errors

Solutions:

Wait and retry — Rate limits reset over time
Check your API usage on provider dashboard

Enable resilience features (auto-retry with backoff):

# ~/.config/whisp/config.toml
[resilience]
enabled = true
max_retries = 3

Switch to a different provider temporarily:
```
whisp config set provider ollama
```

Model Not Found

Symptoms: "Model not found" errors

Solutions:

Check available models for your provider
Update model in config:
```
whisp config set model gpt-4o-mini
```
For Ollama, ensure model is pulled:
```
ollama pull llama3.2
```

Shell Integration Issues

Shortcuts Not Working

Symptoms: ,, ,,, etc. don't do anything

Solutions:

Verify shell integration is sourced:

# For bash
grep whisp ~/.bashrc

# For zsh
grep whisp ~/.zshrc

# For fish
cat ~/.config/fish/conf.d/whisp.fish

Re-source your shell config:
```
source ~/.bashrc  # or ~/.zshrc
```
Check function exists:
```
type ,
```
Should show the function definition.

Reinstall shell integration:

# Re-run the install script or manually add:
source ~/.config/whisp/shell/whisp.bash  # or .zsh or .fish

Error Recovery Not Working

Symptoms: Failed commands don't trigger suggestions

Solutions:

Verify daemon is running:
```
whisp status
```
Check socket exists:
```
ls /tmp/whisp.sock
```
Verify hooks are registered (bash):
```
trap -p DEBUG
echo $PROMPT_COMMAND
```

Test manually:

# Run a command that will fail
cat /nonexistent/file
# Should see "Whisp suggests:" if working

Session ID Issues

Symptoms: ,, shows "No recent query" even after using ,

Solutions:

Check session ID is set:
```
echo $WHISP_SESSION_ID
```
Verify temp file exists after a query:
```
ls /tmp/whisp_last_*
```
Re-initialize shell session:
```
source ~/.bashrc
```

Performance Issues

Slow Responses

Symptoms: Commands take a long time to respond

Solutions:

Check response time metrics:
```
whisp metrics
```

Use a faster model:

whisp config set model gpt-4o-mini  # Faster than gpt-4

Use local inference with Ollama:
```
whisp config set provider ollama
```
Check your network latency to the API provider

High Memory Usage

Symptoms: Whisp daemon using excessive memory

Solutions:

Check memory stats:
```
whisp health
```
Restart the daemon to clear caches:
```
whisp restart
```
Check for stuck connections:
```
whisp health | grep connections
```

Configuration Issues

Config File Not Found

Symptoms: "Configuration file not found" warnings

Solution:

whisp init

This creates the config file at ~/.config/whisp/config.toml.

Config File Permission Warning

Symptoms: "Config file has unsafe permissions" warning

Solution:

chmod 600 ~/.config/whisp/config.toml

This ensures only you can read the config file (which contains API keys).

Invalid Config Format

Symptoms: "Failed to parse configuration" errors

Solutions:

Validate config:
```
whisp config validate
```
Check TOML syntax — Common issues:
- Missing quotes around strings with special characters
- Incorrect indentation in sections
- Duplicate keys

Reset to defaults:

rm ~/.config/whisp/config.toml
whisp init

Getting More Help

Debug Mode

Run the daemon in foreground with verbose output:

whisp stop
whisp start -f

Check Logs

For systemd service:

journalctl --user -u whisp --since "1 hour ago"

Report Issues

If you're still stuck:

Run whisp doctor and note the output
Run whisp health and note the output
Open an issue at github.com/n-f9/whisp/issues

Include:

Your OS and shell version
The diagnostic output
Steps to reproduce the issue

Troubleshooting

This guide covers common issues and their solutions.

Quick Diagnostics

Run the built-in diagnostic tool:

whisp doctor

This checks:

Daemon status
Socket connectivity
Configuration validity
API key configuration
Required dependencies

Daemon Issues

Daemon Won't Start

Symptoms: whisp start hangs or fails silently

Solutions:

Check for existing process:
```
pgrep -f "whisp.*daemon"
```
If a process exists, kill it: pkill -f "whisp.*daemon"
Remove stale PID file:
```
rm /tmp/whisp.pid
```
Remove stale socket:
```
rm /tmp/whisp.sock
```
Try foreground mode for debugging:
```
whisp start -f
```
This shows error messages directly in your terminal.

Daemon Keeps Dying

Symptoms: Daemon starts but stops unexpectedly

Solutions:

Check logs (if using systemd):
```
journalctl --user -u whisp -f
```
Verify API key is valid:
```
whisp doctor
```
Check available memory:
```
free -h
```

Stale Socket/PID

Symptoms: "Daemon already running" but it's not responding

Solution:

rm /tmp/whisp.sock /tmp/whisp.pid
whisp start

Connection Issues

"Daemon not running" Error

Symptoms: Commands show "Daemon not running. Start with: whisp start"

Solutions:

Start the daemon:
```
whisp start
```
Check socket path:
```
ls -la /tmp/whisp.sock
```
Verify socket environment variable:
```
echo $WHISP_SOCKET
```
Should be empty (uses default) or /tmp/whisp.sock

Socket Permission Denied

Symptoms: Can't connect to socket despite daemon running

Solutions:

Check socket permissions:
```
ls -la /tmp/whisp.sock
```
Should be owned by your user.
Restart daemon:
```
whisp restart
```

Timeout Errors

Symptoms: Commands hang then timeout

Solutions:

Check network connectivity (for cloud providers)
Try a different provider temporarily:
```
whisp config set provider ollama
```
Check daemon health:
```
whisp health
```

Provider Issues

API Key Errors

Symptoms: "Invalid API key" or authentication errors

Solutions:

Verify key is set:
```
whisp doctor
```
Re-run setup:
```
whisp init
```

Check environment variable:

# For OpenAI
echo $OPENAI_API_KEY

# For Anthropic
echo $ANTHROPIC_API_KEY

Verify key in config file:

cat ~/.config/whisp/config.toml | grep api_key

Rate Limit Errors

Symptoms: "Rate limit exceeded" or 429 errors

Solutions:

Wait and retry — Rate limits reset over time
Check your API usage on provider dashboard

Enable resilience features (auto-retry with backoff):

# ~/.config/whisp/config.toml
[resilience]
enabled = true
max_retries = 3

Switch to a different provider temporarily:
```
whisp config set provider ollama
```

Model Not Found

Symptoms: "Model not found" errors

Solutions:

Check available models for your provider
Update model in config:
```
whisp config set model gpt-4o-mini
```
For Ollama, ensure model is pulled:
```
ollama pull llama3.2
```

Shell Integration Issues

Shortcuts Not Working

Symptoms: ,, ,,, etc. don't do anything

Solutions:

Verify shell integration is sourced:

# For bash
grep whisp ~/.bashrc

# For zsh
grep whisp ~/.zshrc

# For fish
cat ~/.config/fish/conf.d/whisp.fish

Re-source your shell config:
```
source ~/.bashrc  # or ~/.zshrc
```
Check function exists:
```
type ,
```
Should show the function definition.

Reinstall shell integration:

# Re-run the install script or manually add:
source ~/.config/whisp/shell/whisp.bash  # or .zsh or .fish

Error Recovery Not Working

Symptoms: Failed commands don't trigger suggestions

Solutions:

Verify daemon is running:
```
whisp status
```
Check socket exists:
```
ls /tmp/whisp.sock
```
Verify hooks are registered (bash):
```
trap -p DEBUG
echo $PROMPT_COMMAND
```

Test manually:

# Run a command that will fail
cat /nonexistent/file
# Should see "Whisp suggests:" if working

Session ID Issues

Symptoms: ,, shows "No recent query" even after using ,

Solutions:

Check session ID is set:
```
echo $WHISP_SESSION_ID
```
Verify temp file exists after a query:
```
ls /tmp/whisp_last_*
```
Re-initialize shell session:
```
source ~/.bashrc
```

Performance Issues

Slow Responses

Symptoms: Commands take a long time to respond

Solutions:

Check response time metrics:
```
whisp metrics
```

Use a faster model:

whisp config set model gpt-4o-mini  # Faster than gpt-4

Use local inference with Ollama:
```
whisp config set provider ollama
```
Check your network latency to the API provider

High Memory Usage

Symptoms: Whisp daemon using excessive memory

Solutions:

Check memory stats:
```
whisp health
```
Restart the daemon to clear caches:
```
whisp restart
```
Check for stuck connections:
```
whisp health | grep connections
```

Configuration Issues

Config File Not Found

Symptoms: "Configuration file not found" warnings

Solution:

whisp init

This creates the config file at ~/.config/whisp/config.toml.

Config File Permission Warning

Symptoms: "Config file has unsafe permissions" warning

Solution:

chmod 600 ~/.config/whisp/config.toml

This ensures only you can read the config file (which contains API keys).

Invalid Config Format

Symptoms: "Failed to parse configuration" errors

Solutions:

Validate config:
```
whisp config validate
```
Check TOML syntax — Common issues:
- Missing quotes around strings with special characters
- Incorrect indentation in sections
- Duplicate keys

Reset to defaults:

rm ~/.config/whisp/config.toml
whisp init

Getting More Help

Debug Mode

Run the daemon in foreground with verbose output:

whisp stop
whisp start -f

Check Logs

For systemd service:

journalctl --user -u whisp --since "1 hour ago"

Report Issues

If you're still stuck:

Run whisp doctor and note the output
Run whisp health and note the output
Open an issue at github.com/n-f9/whisp/issues

Include:

Your OS and shell version
The diagnostic output
Steps to reproduce the issue

Troubleshooting

On this page

Troubleshooting

On this page