Troubleshooting
Solutions to common issues. If something's not working, start here.
Files Not Processing
You dropped a file into INGEST/ but nothing happened — it just sits there.
Check the file watcher
On the Status page, look at the Vault Status section. The watcher indicator should show Running. If it shows Stopped or Error:
- Verify the vault directory exists on disk
- Verify the
INGEST/subfolder exists inside it - Check you have read/write permissions on both folders
- Try clicking Rebuild Wiki to restart the watcher
Check the file format
The AI enrichment pipeline only processes .md files (Markdown). If you dropped a PDF, DOCX, or XLSX, it should be auto-converted first. If that conversion fails, the file stays in INGEST/ without becoming a .md file and won't be processed.
Non-supported formats (.pptx, .odt, etc.) are moved to the vault but won't receive AI enrichment. Convert them to PDF or plain text first.
Check API settings
Go to Settings → AI Provider and click Test Connection. If it fails:
- Verify the endpoint URL is correct and ends with
/v1 - Re-enter your API key (it may have expired)
- Make sure you have a model selected
Check for failed files
On the Status page → Queue → Failed Files. Any files that encountered errors during AI processing appear here. You can retry them individually or in bulk.
Quick Notes Hotkey Not Working
macOS: Accessibility permission required
The ⌥ + ⌥ global hotkey requires macOS Accessibility permission to detect key presses system-wide.
Go to System Settings → Privacy & Security → Accessibility.
Click the + button and add Wikori from your Applications folder.
Make sure the toggle next to Wikori is enabled (blue).
Quit and relaunch the app for the permission to take effect.
Wikori will show an in-app prompt asking for Accessibility permission when it first starts, if the permission is missing. If you dismissed that prompt, you need to add it manually as above.
Windows / Linux
The Alt + Alt hotkey should work without any special permissions. If it doesn't:
- Check whether another application has registered the same hotkey
- Try running Wikori as administrator temporarily to test
- On Linux, check if your desktop environment is intercepting Alt key combinations
API Errors
| Error | Cause | Fix |
|---|---|---|
401 Unauthorized | API key invalid or expired | Re-enter your API key in Settings and save |
400 Bad Request | Endpoint URL malformed | Check the URL ends with /v1 and has no trailing slash issues |
404 Not Found | Wrong endpoint path | Verify the base URL — most APIs expect https://api.example.com/v1 |
429 Too Many Requests | Rate limit exceeded | Wait a minute, then retry. Consider reducing batch size. |
5xx Server Error | API provider issue | Retry later. Check the provider's status page. |
| Timeout (60s) | Slow network or large file | Check your internet connection. Very large files may need chunking. |
Office File Extraction Failing
Your PDF, DOCX, or XLSX file landed in the vault but wasn't converted to Markdown and wasn't enriched.
- Password-protected files cannot be extracted. Remove the password before dropping into INGEST/.
- Corrupted files will fail silently. Try opening the file in its native app to verify it's intact.
- Scanned PDFs (images of text) have no text layer for extraction. Run OCR on them first using Preview, Adobe Acrobat, or an online tool.
- Unsupported formats (PPTX, ODT, ODS, ODP): convert to PDF or DOCX manually, then re-ingest.
Encryption & Settings Issues
API token not working after moving to a new machine
Wikori encrypts your API key and email credentials using a key derived from your machine's hardware ID. Encrypted credentials cannot be decrypted on a different machine — this is a security feature.
If you've moved Wikori to a new computer or replaced your hardware, simply re-enter your API key and email password in Settings. They will be re-encrypted for the new machine automatically.
Settings file location
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/wikori/settings.json |
| Windows | %APPDATA%\wikori\settings.json |
| Linux | ~/.config/wikori/settings.json |
Never share your settings.json file — it contains encrypted API credentials. While the encryption is machine-bound, it is still sensitive data.
MCP Server Issues
Agent can't connect to the server
- Verify the server is running: the status badge on the MCP page should show Running
- Check the port — default is 8787. If something else is using port 8787, the server will fail to start.
- Make sure your agent config uses
http://127.0.0.1:8787(notlocalhost, which can resolve differently) - Verify the
AUTH_TOKENorAuthorizationheader matches your MCP secret exactly
Server starts but returns no results
- Make sure you have at least one vault configured with a directory
- Process some files first — empty vaults return empty results
- Rebuild the wiki on the Status page to refresh the knowledge index
Knowledge Map is Empty
The graph shows "No entities found" even though you have files in your vault.
- Go to the Status page and click Rebuild Wiki. The graph only updates after a rebuild.
- Make sure your files have been processed by the AI pipeline (they should have YAML frontmatter at the top). Unprocessed files won't appear in the graph.
- Entities are extracted by the AI model. If your model returns minimal metadata, few nodes may appear. Consider using a more capable model.