---
title: Troubleshooting
description: Common issues and how to fix them.
---

# Troubleshooting

Fixes for the most common Vault Operator issues. If your problem isn't here, check the **Debug** tab in settings or ask in the community forum.

## Model connection issues

Symptom: "Connection failed" or "API key invalid" when testing a model.

| Cause | Solution |
|-------|----------|
| Wrong API key | Double-check the key in **Settings > Models**. Regenerate it at the provider's website if unsure. |
| Expired key | Some providers expire keys after inactivity. Generate a new one. |
| Wrong base URL | For Azure and custom endpoints, verify the full URL including `/v1` if required. |
| Rate limited | Wait a few minutes and try again. Consider setting a rate limit in **Settings > Loop**. |
| Firewall or proxy | Obsidian uses Electron's network stack. Check that your firewall allows outbound HTTPS. |

:::tip Test button
Always use the **Test connection** button after adding or changing a model. It verifies the key, endpoint, and model name in one step.
:::

## Semantic search not working

Symptom: `semantic_search` returns no results, or the agent says the index is not available.

| Cause | Solution |
|-------|----------|
| No embedding model configured | Go to **Settings > Embeddings** and set up an embedding model (e.g., OpenAI `text-embedding-3-small`). |
| Index not built | Click **Rebuild index** in **Settings > Embeddings**. First build can take a few minutes for large vaults. |
| Embedding API key missing | The embedding model may need its own API key. Check the embeddings settings. |
| Auto-index disabled | If auto-index is off, new or changed notes won't be indexed. Enable it or rebuild manually. |
| Vault too large | For vaults with 10,000+ notes, the initial build may take a while. Let it finish before searching. |

## Agent stuck in a loop

Symptom: The agent keeps calling tools repeatedly without making progress, or hits the iteration limit.

| Cause | Solution |
|-------|----------|
| Weak model | Smaller or older models sometimes repeat themselves. Switch to a stronger model (Claude Sonnet, GPT-4o). |
| Consecutive error limit too high | Lower it in **Settings > Loop > Consecutive error limit** (default: 3). |
| Max iterations too high | Set a reasonable cap in **Settings > Loop > Max iterations** (default: 25). |
| Tool permission denied repeatedly | The agent asks for approval but you haven't responded. Approve or deny to let it continue. |
| Context overflow | Enable **context condensing** in **Settings > Loop**. Lower the condensing threshold if you see 400-errors. |

:::info Emergency stop
Click the **Stop** button in the chat toolbar at any time to halt the agent. You can undo any changes already made via the checkpoint system.
:::

## Permission issues

Symptom: The agent says it cannot perform an action, or approvals keep appearing for routine tasks.

| Cause | Solution |
|-------|----------|
| Auto-approve not enabled | Go to **Settings > Permissions** and enable auto-approve for categories you trust. |
| File is in the ignore list | Check `.obsidian-agentignore` in your vault root. Remove the path if the agent should access it. |
| File is protected | Check `.obsidian-agentprotected`. The agent can read but not write these files. |
| Mode restricts tools | The current mode may not include the needed tool group. Switch to Agent mode or edit the mode's tools. |

## MCP server not connecting

Symptom: "Failed to connect" or "Server unreachable" when adding or using an MCP server.

| Cause | Solution |
|-------|----------|
| Wrong transport type | Only **SSE** and **streamable-http** are supported. Stdio doesn't work in Obsidian's Electron runtime. |
| Server not running | Verify the MCP server is running and accessible at the configured URL. |
| Wrong URL | Check the server URL. Common format: `http://localhost:3000/sse` or `http://localhost:3000/mcp`. |
| CORS issues | If the MCP server runs locally, it may need CORS headers. Check the server's documentation. |
| Network timeout | Increase the connection timeout in the MCP server settings, or check your network. |

## Performance problems

Symptom: Obsidian feels slow, the agent takes a long time, or the UI lags.

| Cause | Solution |
|-------|----------|
| Large vault indexing | The semantic index build runs in the background. Wait for it to finish. |
| Too many concurrent sub-agents | Limit subtask depth in **Settings > Loop** (default: 2). |
| Large context window | Enable context condensing to keep the conversation from growing too large. |
| Many MCP servers | Each connected server maintains an active connection. Remove unused servers. |
| Slow model | Local models on limited hardware can be slow. Try a smaller model or use a cloud provider. |

## Knowledge database errors

Symptom: The plugin logs "knowledge.db is corrupt", "database is locked", "integrity check failed", or semantic search and memory tools return nothing after a crash or sudden Obsidian quit.

| Cause | Solution |
|-------|----------|
| Corrupt write after a crash or power loss | The plugin runs an `integrity_check` and auto-recovers from the last good state on the next open. Reopen Obsidian. If it does not recover, restore from `.obsidian/plugins/vault-operator/.bak/{db-name}/{YYYY-MM-DD}.db` (daily snapshots, 7-day retention). |
| Another Obsidian window has the database open | A second running instance holds a lock file. Close the other window or restart Obsidian. |
| Storage mode mismatch after switching `global` ↔ `local` | A switch resets the active database. Set the desired mode in **Settings > Embeddings > Storage location** and rebuild the index. |
| Database wedged after a failed upgrade | Quit Obsidian. Move `knowledge.db` and `knowledge.db-journal` aside and copy the most recent file from the `.bak/` snapshot folder into place. Reopen. |
| Semantic index missing after restoring a vault from backup | The index lives outside the vault. Open **Settings > Embeddings** and click **Rebuild index**. |

:::warning Do not delete `knowledge.db` while Obsidian is running
The lock file is held by the live process. Quit Obsidian first, then move or restore the file. Deleting it mid-run drops all embeddings, the memory store, and the conversation history index, and requires a full reindex.
:::

## `write_file` is truncated mid-output

Symptom: The agent calls `write_file`, but the file ends mid-sentence or shows a JSON parse error in the activity block. Often followed by repeated retry loops and a final 400 context-overflow error.

| Cause | Solution |
|-------|----------|
| `max_tokens` too low for the model | Open **Settings > Models**, edit the active model, and switch on **Automatic (recommended)** for max output tokens. The plugin then clamps the output budget to the model's real ceiling minus the estimated input. |
| Manual `max_tokens` plus a large thinking budget | For Anthropic and Bedrock, `max_tokens` covers the thinking budget AND the visible output. A configured `max_tokens=8192` with a `thinking_budget=10000` leaves nothing for the visible tool call. Set **Automatic** or raise `max_tokens` well above the thinking budget. |
| Very long file in a single call | Ask the agent to split the file: `write_file` for the head section, then `append_to_file` calls for the following sections. The built-in prompt already nudges the model to do this for content above 2000 words. |
| Repeated parse-error loop after a truncation | The agent now reports the real provider error back into the tool result and trips the consecutive-mistake circuit breaker after three retries (default). If the loop survives, click **Stop** and start a fresh conversation. |

## Context overflow on long conversations

Symptom: A 400 error with `context_length_exceeded`, `prompt is too long`, or the conversation suddenly stops responding.

| Cause | Solution |
|-------|----------|
| Conversation too long for the model's context window | Enable **Context condensing** in **Settings > Loop**. The plugin keeps a stable cache-aligned prefix and condenses older turns. |
| Threshold set too high | Lower **Condensing threshold** to 0.6 or 0.7. The plugin also runs an emergency condensing pass on any 400 context-overflow error. |
| Very large @-mention attached to the chat | Plaintext, Markdown, and XML attachments are now capped at 80,000 characters with a `read_file path=...` hint. Older builds injected the full text. Update the plugin, or split the source into smaller notes. |
| Long tool output filling the context | Enable **Context externalization** in **Settings > Loop**. Large tool outputs are written to a temp file and the conversation keeps a compact reference (`read_file path=...`) instead of the full payload. |

## Memory not extracting

Symptom: The agent doesn't remember things from previous conversations.

| Cause | Solution |
|-------|----------|
| Memory extraction disabled | Enable it in **Settings > Memory > Memory extraction**. |
| Chat history disabled | Memory extraction requires saved conversations. Enable **Chat history** first. |
| Threshold too high | Lower the **Memory threshold** in settings (default: 0.7). A value of 0.5 captures more memories. |
| Wrong memory model | If the memory model isn't configured or is offline, extraction silently fails. Check **Settings > Memory > Memory model**. |
| Short conversations | Very brief exchanges may not contain extractable facts. This is normal. |

## Common error messages

| Error | Meaning | Fix |
|-------|---------|-----|
| `400: context_length_exceeded` | The conversation is too long for the model's context window. | Enable context condensing. Start a new chat for fresh context. |
| `400: tool_use ids were found without tool_result` | Anthropic / Claude-via-Copilot rejected the request because the conversation history had an orphan tool call. Usually caused by an aborted stream or a resumed crashed conversation. | v2.5.0 sanitises the history automatically on every API call, so this should no longer surface. If it does, start a new conversation. |
| `400: Unsupported parameter: 'max_tokens' is not supported` | Old Copilot code path sending the wrong token-limit parameter. | v2.5.0 sends `max_completion_tokens` for every Copilot model. Update Vault Operator. |
| `401: Unauthorized` | Invalid or expired API key. | Re-enter the key in Settings > Models. |
| `429: Rate limit exceeded` | Too many API calls in a short time. | Set a rate limit in Settings > Loop, or wait and retry. |
| `ECONNREFUSED` | Local server (Ollama, LM Studio) isn't running. | Start the local server, then retry. |
| `Checkpoint failed` | Could not create a file snapshot before editing. | Check disk space. Increase snapshot timeout in Settings > Vault. |
| Drawio / Diagrams plugin says "Not a diagram file" when opening a file the agent wrote | Hand-authored `.drawio.svg` without a valid mxfile wrapper. | Delete the broken file. Ask the agent again. v2.5.0 blocks direct `write_file` for `.drawio.svg` and routes to the built-in `create_drawio` tool, which writes a plugin-compatible format. |

:::tip Debug tab
The **Debug** tab in settings shows the agent's internal ring buffer (last 100 log entries), the generated system prompt, and connection status for each provider. Start here when something behaves unexpectedly.
:::
