Troubleshooting

Troubleshooting

Common issues and solutions for Vaultend.

---

How Errors Are Reported

Vaultend uses three levels of error reporting. Understanding this helps you find the right information when something goes wrong.

Level	Where it appears	What it covers
Notice banner	Obsidian UI (top-right popup)	User-triggered action failures — organize errors, apply failures, embedding init failures
Console log	Developer console (Ctrl/Cmd + Shift + I)	All of the above, plus internal failures — search index errors, link selection failures, batch processing details
Silent	Nowhere visible	Best-effort background tasks — cache saves, index updates, embedding sync. These are non-critical and auto-recover on next startup

What "silent" means

Some background operations (cache persistence, search index cleanup, embedding synchronization) are intentionally silent. If they fail:

• Your data is safe — these operations don't modify notes
• Core features keep working — organize, maintenance, and tag management are unaffected
• Auto-recovery — caches and indexes rebuild automatically on next plugin load

You do NOT need to take any action for silent failures.

---

AI Provider Issues

"AI error" or API errors

Symptoms: Notice shows "AI error [provider] (status): detail"

Solutions:

1. Check your API key — go to Settings → Vaultend → AI Provider and verify the key is correct
2. Check your balance — ensure your API account has sufficient credits
3. Check the model — some models may be deprecated or unavailable. Try a different model from the dropdown.
4. Rate limits — if you see rate limit errors, wait a moment and try again. Batch operations may hit rate limits with some providers.

Embedding features not working

Symptoms: Tag similarity, cross-language tag detection, or link suggestions don't work properly

Solutions:

1. Check embedding support — your AI provider must support embeddings. See Settings → Embedding Support.
2. Ollama users — install an embedding model: ollama pull nomic-embed-text
3. Custom provider — verify your endpoint supports the embeddings API
4. Check the embedding model setting — ensure the specified embedding model exists and is accessible

"Embedding model failed to initialize"

This notice appears on plugin load if the embedding model can't be reached.

Solutions:

1. Check your API key and network connection
2. Verify the embedding model name in Settings
3. Link suggestions may be temporarily unavailable — core features (tag suggestion) still work

Console detail: Open developer console to see the specific error: Vaultend: embedding initialization failed or Vaultend: AI config change re-initialization failed

Cost estimate shows "N/A"

The cost display says "Cost: N/A" when the model you're using is not in the plugin's built-in pricing table. Token counts are still accurate (they come directly from the API).

Solutions:

• This is cosmetic only — AI features work normally
• Check your actual cost at your provider's usage dashboard
• The pricing table is updated with each plugin release

See Settings → Token & Cost Display for details on what's exact vs. approximate.

---

Organize Issues

No tags suggested

Possible causes:

• Note content is too short for meaningful analysis
• Note content was truncated (notes over 15,000 characters are automatically truncated)
• AI confidence was below threshold (if confidence gating is enabled)

No links suggested

Possible causes:

• No related notes exist in your vault
• Embedding model is not configured (see above)
• Link similarity threshold may be too high — try lowering it in Settings → Link Suggestion

Console detail: If link suggestion failed internally, you'll see Vaultend: LLM link selection failed or Vaultend: embedding link computation failed in the developer console. The organize result will still return successfully — just without links.

Organize seems to take a long time

• Large notes take longer to process
• Batch operations (Organize Folder) process notes sequentially and may take several minutes for large folders
• Network latency to your AI provider can affect speed

Same results after editing a note

The plugin caches organize results in memory per session. If you edit a note and organize again:

• Content changed → cache is invalidated automatically, AI runs again
• Content unchanged → cached result is returned

To force a fresh AI call, click Re-organize in the result modal.

---

Maintenance Issues

Some notes not appearing in scan results

Possible causes:

• Notes are in an excluded folder (check Settings → Maintenance → Exclude Folders)
• Notes have an excluded tag (check Settings → Maintenance → Exclude Tags)
• Non-Markdown files (.excalidraw.md, .canvas) are automatically excluded

Auto maintenance not running

1. Check that Auto Maintenance is enabled in Settings
2. Smart scheduling: If no files have changed since the last scan, the scheduled scan is skipped. This is by design to save resources.
3. Check the maintenance interval setting

Console detail: If a scheduled maintenance fails, you'll see Vaultend: scheduled maintenance failed in the developer console, along with a Notice banner.

False positive duplicates

Duplicate detection uses TF-IDF cosine similarity. Very short notes or notes with common vocabulary may produce false positives. You can:

• Dismiss false positives (they won't appear again)
• Use the Open Side by Side button to compare before taking action

---

Privacy Issues

Excluded notes still being sent to AI

Privacy rules are processed in order. Check:

1. The rule is enabled (toggle is on)
2. The pattern is correct (folder paths are case-sensitive)
3. The rule type matches your intent (folder exclude vs tag exclude vs properties exclude)

Content redaction not working

1. Check that the regex pattern is valid
2. For simple word masking, just type the word (no regex knowledge needed)
3. Redaction only applies to data sent to AI — your original notes are never modified

Console detail: If a redaction regex is invalid, you'll see [Vaultend] Invalid content-redact pattern, skipped: "..." in the developer console. The invalid rule is skipped but other rules still apply.

---

General Issues

Plugin not loading

1. Check Obsidian version — minimum 1.7.2 required
2. Try disabling and re-enabling the plugin in Settings → Community Plugins
3. Check the developer console (Ctrl/Cmd + Shift + I) for error messages

Commands not appearing in Command Palette

• Organize Current Note — only appears when a note is open in the editor
• After changing the display language, command palette names update after restarting Obsidian

Undo not working

• The toast undo button is available for 10 seconds after applying changes
• For older actions, use the Activity Log → click Restore
• Some restore operations may fail if the note was modified by other means after the action

Batch operations show "N failed"

When batch organizing or batch applying actions, some individual notes may fail while others succeed. The result notice shows the count (e.g., "5 succeeded, 2 failed").

Possible causes:

• Individual notes had file access issues
• AI API returned errors for specific notes (rate limit, content too long)

Console detail: Open developer console to see per-note failure details: Vaultend: batch read failed for <path> or Vaultend: batch apply failed for <path>

---

Using the Developer Console

For any issue not covered above:

1. Open the developer console: Ctrl/Cmd + Shift + I → Console tab
2. Filter by typing Vaultend in the console filter box
3. Look for messages prefixed with Vaultend: (errors) or [Vaultend] (warnings)

All Vaultend console messages use one of these prefixes, making them easy to find among other plugin logs.

---

Reporting Bugs

If you can't resolve your issue:

1. Open the developer console (Ctrl/Cmd + Shift + I) and filter for "Vaultend"
2. Note any error messages you see
3. Create an issue at GitHub Issues
4. Include: Obsidian version, Vaultend version, AI provider, and the error message