> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpawz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them.

# Troubleshooting

Common issues and how to fix them.

## Build issues

### Rust compilation fails

**Symptoms:** `cargo build` errors, missing system dependencies

**Fix:**

```bash theme={null}
# 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:

```bash theme={null}
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:**

```bash theme={null}
# Check Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve
```

### Model not found

**Symptoms:** "Model not found" error

**Fix:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
# 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.