← Grimoire
Source on GitHub Docs

Troubleshooting & FAQ

Quick orientation lives on grimoireapp.dev/help/; this page goes deeper for docs.grimoireapp.dev readers.

Ollama and the assistant

Symptoms: Chat errors, “unavailable” messages, or embeddings never finishing.

Checks:

  1. Is Ollama running? From a terminal, ollama serve if you do not use a background service.
  2. Did you pull the chat model you selected and the embedding model from Settings → LLM? Defaults often include nomic-embed-text for embeddings — run ollama pull <name> for whatever you configured.
  3. After changing the embedding model, did you run the clear index & re-index flow? Old vectors are not compatible across models.

Structured error kinds (OllamaUnavailable, EmbeddingFailed) and the authoritative table live in AI assistant — Common errors.

RAG returns nothing useful

Is this normal sometimes? Yes — retrieval depends on indexes, toggles, and whether content is unlocked.

Checks:

  1. In chat, confirm “Use notes” (and any other context sources you expect) are on (AI assistant).
  2. Run search (Ctrl+F) on the same keywords — if semantic search is empty, you may still be re-indexing or using the wrong embedding model. See Search.
  3. Locked folders and a locked vault exclude ciphertext from normal flows — unlock before expecting RAG hits inside encrypted scopes (Privacy & security).

Wikipedia offline, catalogue, or indexing

Symptoms: “No internet”, catalogue fetch fails, or indexing stalls/errors.

Checks:

  1. Settings → Wikipedia — confirm storage path is set before downloading bundles.
  2. Fetch catalogue requires outbound HTTPS to discover bundles; reading articles and indexing use local CPU and Ollama once a .zim is on disk.
  3. After changing the embedding model and re-indexing notes, the LLM settings UI reminds you to re-index Wikipedia (and file scanner) from their own panels.

See Settings glossary — Wikipedia and Views — Wikipedia.

File Scanner permissions and paths

Symptoms: “Could not add folder”, scan errors, or stale files after you moved things.

Checks:

  1. File Scanner is for external files — do not treat the Grimoire app data directory or the note database as a scan root. Notes are already indexed via the normal note pipeline (Vault & data, Settings — File Scanner).
  2. On some OSes, sandboxing / permissions may block reads of certain directories — pick folders your user can read.
  3. If a root moved, the UI surfaces missing path / stale file counts — use Clean up or Remove as appropriate.

Backing up or relocating app data

Notes live under the com.grimoire.app app data directory, not a user-chosen vault folder. See Vault & data for paths.

If you need to back up or move data:

  1. Quit Grimoire completely (do not leave another instance open).
  2. Copy the entire app data folder (grimoire.db, lancedb/, and siblings) to your backup or new location.
  3. To restore on the same machine profile, replace the contents of that app data directory while the app is quit.
  4. Never run two Grimoire instances against the same SQLite file — corruption risk is real.

Always keep a known-good copy before experimenting. Prefer Markdown export when you only need portable text.

Performance tips

Installers vs source builds

Installers for current releases ship on Download (Windows, macOS, Linux). See Installers & uninstall for trust warnings and data survival on uninstall.

From source remains available for contributors and platforms where you prefer a local build — see Getting started and builds-and-installers.md for native prerequisites.

Still stuck?