Skip to main content

Common Issues

Solutions for frequently encountered problems.

Connection Issues​

"Daemon is not running"​

Symptom:

OWL daemon is not running!

Solution:

The daemon auto-starts when you run owl. If it fails:

# Check if Ollama is running first
ollama serve

# Then start OWL
owl

Or start the daemon manually:

owl start

"Cannot connect to Ollama"​

Symptom:

Cannot connect to Ollama at http://localhost:11434

Solutions:

  1. Start Ollama:
ollama serve
  1. Check it's running:
curl http://localhost:11434/api/tags
  1. If using remote Ollama, configure in ~/.owl/config.yaml:
llm:
  host: http://<host-ip>:11434

Model Issues​

"Model not found"​

Symptom:

Model 'llama3.2' not found

Solution:

# Pull the model
ollama pull llama3.2

# Or use a different model in ~/.owl/config.yaml
llm:
  model: mistral:latest

"No embedding model"​

Symptom: Knowledge base operations fail.

Solution:

ollama pull nomic-embed-text

Installation Issues​

"owl: command not found"​

Symptom: After installation, owl command not found.

Solutions:

  1. Add to PATH (uv tool install location):
export PATH="$HOME/.local/bin:$PATH"
  1. Add to shell profile (~/.bashrc or ~/.zshrc):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  1. Reinstall:
curl -sSL https://kavin-ps.io/owl/install.sh | bash

Tool Issues​

"Tool not available"​

Symptom:

Tool not available: write_file (profile: minimal)

Solution:

/tools coding   # Enable write tools
/tools full     # Enable all tools

"Can only write to home directory"​

Symptom: Write operations fail outside home/tmp.

Solution: This is a safety feature. Work within your home directory.

Memory Issues​

Memory not persisting​

Check:

  1. ~/.owl/ directory exists
  2. Files are writable
  3. Daemon has write permissions

Reset:

rm -rf ~/.owl
owl  # Restart - will recreate directory

"File too large"​

Symptom:

File too large (>1MB)

Solution: Read specific line ranges:

you: Read lines 1-100 of large-file.py

Performance Issues​

Slow responses​

Causes:

  • Large model
  • Insufficient RAM
  • Many tools active

Solutions:

  1. Use smaller model in ~/.owl/config.yaml:
llm:
  model: mistral:latest
  1. Increase timeout:
llm:
  timeout: 180

High memory usage​

Solution: Summarization kicks in after 20 messages. For immediate relief:

/new  # Start fresh session

Socket Issues​

"Address already in use"​

Symptom: Daemon fails to start.

Solution:

# Remove stale socket
rm ~/.owl/owl.sock

# Or find and kill old process
lsof ~/.owl/owl.sock
kill <PID>

# Or use owl stop
owl stop

Reset Everything​

Nuclear option - start completely fresh:

owl stop
rm -rf ~/.owl
owl  # Fresh start

This removes:

  • Configuration
  • Memory
  • Knowledge base
  • Soul
  • Conversation history