Troubleshooting

If something isn’t working as expected, this page covers the most common issues and their solutions. Start with the section that matches your problem.

---

Installation Issues

macOS: “Ariv can’t be opened because it is from an unidentified developer”

Ariv is properly signed and notarized by Apple, but since it’s distributed outside the Mac App Store, macOS Gatekeeper may block the first launch.

Fix:

1. Open Finder and navigate to Applications.
2. Right-click (or Control-click) on Ariv.
3. Select Open from the context menu.
4. Click Open in the dialog that appears.

This only needs to be done once. After that, Ariv opens normally.

macOS: “Ariv is damaged and can’t be opened”

This can happen if macOS quarantine attributes were incorrectly applied during download.

Fix: Open Terminal and run:

xattr -cr /Applications/Ariv.app

Then try opening Ariv again. This removes the quarantine flag that macOS places on downloaded files.

Windows: SmartScreen warning

Windows SmartScreen may show a warning because Ariv is a newer application that hasn’t yet built up extensive download reputation with Microsoft.

Fix:

1. Click More info on the SmartScreen dialog.
2. Click Run anyway.

This only appears on the first launch. The app is safe — SmartScreen warnings are based on download volume, not security analysis.

---

Startup Issues

App shows blank or white screen

This is typically a rendering issue related to hardware acceleration.

Fix (if you can access Settings):

1. Open Settings > Advanced.
2. Turn off Hardware Acceleration (advanced.hardwareAcceleration).
3. Restart Ariv.

Fix (if you can’t access Settings): Delete the settings file and relaunch:

• macOS: ~/Library/Application Support/Ariv/settings.json
• Windows: %APPDATA%/Ariv/settings.json

Ariv will recreate the settings file with defaults on next launch.

Caution

Deleting settings.json resets all your preferences to defaults. Your notes and vault are not affected — only app settings like theme, keybindings, and AI configuration.

App crashes on launch

If Ariv crashes immediately on startup, the local database may be corrupted.

Fix:

1. Navigate to the Ariv data directory:
   • macOS: ~/Library/Application Support/Ariv/
   • Windows: %APPDATA%/Ariv/
2. Delete any *.db files in that directory.
3. Relaunch Ariv.

Ariv will rebuild the database and re-index your vault automatically. Your notes are plain files on disk and are never affected by database issues.

Note

Re-indexing a large vault may take a minute on first launch after deleting the database. This is a one-time process.

---

Performance

Slow startup with a large vault

Initial indexing of large vaults (10,000+ notes) can take up to a minute or more. This is a one-time operation — subsequent launches are fast because only changed files need to be re-indexed.

If startup remains slow after initial indexing:

• Check the advanced.fileWatcherDelay setting (default: 300ms). For very large vaults, increasing this value reduces file system overhead.
• Ensure your vault isn’t stored on a network drive or slow external storage. Local SSDs perform best.

Editor feels laggy

Several factors can affect editor performance:

Try these fixes in order:

1. Disable hardware acceleration — Go to Settings > Advanced and turn off advanced.hardwareAcceleration. Restart Ariv.
2. Disable spell check — Spell checking on long documents can cause lag.
3. Check note length — Very long notes (10,000+ lines) may be slow to render. Consider splitting them into smaller notes.

High memory usage

Ariv’s memory footprint grows with the number of open panes and cached content.

To reduce memory usage:

• Close unused split panes and tabs.
• Disable semantic search in Settings > AI if you don’t use it (the local model consumes memory).
• Restart the app to clear all caches.

---

Files & Notes

Notes not appearing in the file tree

If you know a file exists in your vault but it doesn’t show up in Ariv:

1. Check excluded folders. Open Settings > Files and review files.excludedFolders. Your folder may be in the exclusion list. Default exclusions are: .git, node_modules, .obsidian.
2. Check file extension. Ariv only indexes .md files. Files with other extensions (.txt, .markdown, etc.) won’t appear.
3. Check file location. Make sure the file is inside your configured vault folder, not in a sibling directory.

Tip

If you use Obsidian alongside Ariv, the .obsidian folder is excluded by default. This is intentional — it contains Obsidian configuration files, not notes.

Daily note created in the wrong folder

The daily note location is controlled by the files.dailyNotesFolder setting.

Fix:

1. Open Settings > Files.
2. Update files.dailyNotesFolder to your preferred path (default: Daily Notes - Ariv).

Existing daily notes are not moved. Only new daily notes will use the updated path.

Deleted files still appearing

Ariv uses a file system watcher to detect changes. If files were deleted by an external tool or sync service, there may be a brief delay before the change is reflected.

Fix:

• Wait a few seconds for the file watcher to catch up.
• If the file persists, restart Ariv. This forces a full re-scan of the vault.

---

AI Features

”Invalid API key” error

This means the API key you entered is not being accepted by the provider.

Checklist:

1. Open Settings > AI & Intelligence.
2. Verify you selected the correct provider (Gemini, OpenAI, Anthropic, or Ollama).
3. Make sure the API key matches the selected provider — a Gemini key won’t work with the OpenAI provider.
4. Check for leading or trailing spaces in the key.
5. Verify the key is still active in your provider’s dashboard (keys can expire or be revoked).

Note

API keys are stored securely and separately from your regular settings file. They are never included in logs or telemetry.

Ask Brain returns “I don’t have enough information”

This response means Ariv’s search didn’t find notes relevant enough to answer your question.

Things to try:

• Rephrase your question. Use different keywords or be more specific about what you’re looking for.
• Check your vault size. Ask Brain works best with a well-populated vault. If you only have a handful of notes, the AI may not have enough context.
• Increase context notes. Raise the ai.maxContextNotes setting (default: 10, max: 50) to include more notes in each query.
• Verify indexing is complete. If you recently added many files, the vault may still be indexing. Check the status bar for indexing progress.

Semantic search not working

Semantic search uses a local embedding model that needs to be downloaded once before it works.

Checklist:

1. Ensure ai.semanticSearch is enabled in Settings > AI.
2. The model is approximately 22MB and downloads on first use. Check your internet connection if the download hasn’t completed.
3. After downloading, semantic search works fully offline.

If the model download seems stuck, restart Ariv and it will retry the download.

Ollama not connecting

Ollama is a local AI runtime that must be installed and running separately from Ariv.

Checklist:

1. Verify Ollama is running. Open a terminal and run ollama serve. You should see it start listening on a port.
2. Check the URL. In Settings > AI, verify the Ollama URL is correct (default: http://localhost:11434).
3. Verify your model is pulled. Run ollama pull llama3.1:8b (or your preferred model) to ensure it’s downloaded locally.
4. Check for port conflicts. If another service is using port 11434, Ollama won’t start. Check with lsof -i :11434 (macOS) or netstat -an | findstr 11434 (Windows).

Tip

For the best local AI experience, llama3.1:8b provides a good balance of quality and speed. Larger models like llama3.1:70b give better answers but require significantly more RAM and are slower.

---

Search

Search not finding known content

If full-text search isn’t returning results you know exist in your notes:

1. Check your search terms. FTS5 search is word-based. Partial words may not match — try the complete word.
2. Rebuild the index. Close and reopen your vault. This triggers a re-scan and can fix stale index entries.
3. Database rebuild. If the issue persists after reopening, the FTS5 index may need rebuilding. Delete the *.db files from the Ariv data directory (see App crashes on launch above for the path) and relaunch. The database will be rebuilt from your files.

---

Auto-Updates

Update not installing

Ariv checks for updates automatically each time it launches. If an update is available but not installing:

1. Check your internet connection. Update checks require a network connection to Cloudflare R2.
2. Restart Ariv. The update check happens on launch — a fresh restart triggers a new check.
3. Download manually. If the auto-updater isn’t working, download the latest version directly from ariv.one and install it over your existing installation. Your notes and settings are preserved.

Note

The auto-updater compares version numbers. If you’re already on the latest version, no update prompt will appear. Check Settings or the About dialog to see your current version.

---

Still stuck?

If none of the above solutions resolve your issue:

1. Use the in-app Feedback button to report the problem. Include as much detail as possible: what you were doing, what happened, and your platform (macOS/Windows) and app version.
2. Check for app updates — the issue may already be fixed in a newer version.

---

Related: FAQ — Common questions about Ariv | Privacy & Data — How Ariv handles your data