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. |
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. |
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. |
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. |
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.