Skip to main content

​
Troubleshooting

Common issues and how to fix them.

​
Build issues

​
Rust compilation fails

Symptoms: cargo build errors, missing system dependencies Fix: 
# Ubuntu/Debian
sudo apt install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev

# macOS
xcode-select --install

​
Node.js errors

Symptoms: pnpm install fails, version mismatch Fix: Ensure Node.js 18+ and pnpm are installed: 
node --version  # should be 18+
pnpm install

​
Provider issues

​
”No providers configured”

Symptoms: Agent can’t respond, no model available Fix: Add at least one provider in Settings → Providers.

​
Provider returns errors

Symptoms: Billing, auth, or rate limit errors Fix:
  1. Check your API key is valid
  2. Check your account has credits
  3. Add a second provider for automatic fallback

​
Ollama not detected

Symptoms: Pawz doesn’t see local Ollama Fix: 
# Check Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

​
Model not found

Symptoms: “Model not found” error Fix: 
# For Ollama — pull the model
ollama pull llama3.1

# For cloud providers — check the exact model name

​
Memory issues

​
Embeddings fail

Symptoms: Memory search returns no results, embedding errors Fix: 
# Ensure embedding model is installed
ollama pull nomic-embed-text

# Check Ollama is running
curl http://localhost:11434/api/tags

​
Old memories have no embeddings

Symptoms: Memories created before embedding setup don’t appear in search Fix: Use the backfill button in Memory Palace to retroactively embed all memories.

​
Channel issues

​
Channel won’t connect

Symptoms: Channel status stays “disconnected” Fix:
  1. Verify the bot token is correct
  2. Check network connectivity
  3. Ensure the bot has proper permissions on the platform
  4. Check the Pawz logs for error details

​
Messages blocked

Symptoms: Some messages aren’t getting through Cause: Prompt injection scanner is blocking messages with critical severity. Fix: This is working as intended — the messages contained injection patterns. Check the logs to see what was blocked.

​
Bot not responding in groups

Symptoms: Bot works in DMs but not in group chats Fix:
  • Telegram: Disable Group Privacy in @BotFather
  • Discord: Ensure the bot has “Read Message History” permission
  • Slack: Invite the bot to the channel with /invite @bot

​
Docker sandbox

​
”Docker not available”

Symptoms: Container sandbox fails Fix: 
# Check Docker is running
docker info

# On Linux, ensure your user is in the docker group
sudo usermod -aG docker $USER

​
Container times out

Symptoms: Commands hit the timeout limit Fix: Increase the timeout in Settings → Advanced → Container Sandbox.

​
Performance

​
Slow responses

Causes:
  1. Large context — use /compact to summarize older messages
  2. Too many memories — reduce recall_limit in memory settings
  3. Slow model — switch to a faster model (gpt-4o-mini, gemini-2.0-flash)
  4. Ollama on CPU — use a smaller model or get a GPU

​
Chat behavior

​
Agent keeps repeating the same failed approach

Symptoms: The agent tries the same broken tool call over and over. What Pawz does: Failed tool exchanges are automatically deleted from context before each turn, so the agent gets a clean slate on retry. If you’re still seeing loops, the agent may be hitting a genuine capability limitation. Fix:
  1. Send a new message with more specific instructions
  2. Try a different model with stronger reasoning (e.g., Claude Sonnet 4, Gemini 2.5 Pro)
  3. Start a new session with /new for a completely fresh context

​
Can I send messages while the agent is working?

Yes. Pawz queues your message automatically. The active agent wraps up at the next tool-call boundary, then processes your queued message. You don’t need to wait for a response before typing.

​
High memory usage

Fix:
  • Reduce max_concurrent_runs in Settings → Engine
  • Use smaller models
  • Close unused browser profiles

​
Logs

Check the Tauri logs for detailed error information: 
# Linux
~/.local/share/com.openpawz.openpawz/logs/

# macOS
~/Library/Logs/com.openpawz.openpawz/
Use /debug in any chat to toggle debug mode for verbose output. Use /status to see current engine configuration and provider status.