--- title: "Troubleshooting" description: "Common issues and solutions for Basic Memory." canonical_url: "https://docs.basicmemory.com/reference/troubleshooting" --- # Troubleshooting > Common issues and solutions for Basic Memory. This guide covers common issues and their solutions. For live help, visit our [Discord server](https://discord.gg/tyvKNccgqN). --- ## MCP Connection Issues ### Claude Says "No Basic Memory Tools Available" **Problem:** Claude Desktop can't find Basic Memory tools. **Solutions:** 1. **Check absolute paths** - Use complete paths in Claude Desktop config:```json { "mcpServers": { "basic-memory": { "command": "/Users/yourusername/.local/bin/uvx", "args": ["basic-memory", "mcp"] } } } ```
Find your path with: `which uvx` 2. **Verify installation**:```bash basic-memory --version ``` 3. **Restart applications** - Close and reopen both Terminal and Claude Desktop 4. **Check index status**:```bash basic-memory status ``` ### ENOENT Error **Problem:** Claude Desktop cannot find the `uv` installation. **Solution:** 1. Find the absolute path: `which uvx` 2. Update Claude Desktop config with the full path 3. Restart Claude Desktop ### HTTP MCP Server Not Reachable From Another Machine or Container **Problem:** After upgrading to v0.24, a client on another machine, VM, or container can no longer connect to `bm mcp --transport streamable-http` or `--transport sse`. Requests may also be rejected with a Host or Origin error. **Cause:** Since v0.24, the HTTP transports bind to `127.0.0.1` by default instead of `0.0.0.0`, because the HTTP server has no authentication. On a loopback bind, requests whose `Host` or `Origin` header is foreign are rejected to block DNS rebinding. **Solutions:** 1. **Bind to all interfaces deliberately**, only on a network you trust:```bash bm mcp --transport streamable-http --host 0.0.0.0 --port 8000 ```
The command prints a warning that the server is reachable without authentication. 2. **Allow a specific hostname or origin**, for example a reverse proxy or a browser-based client, with FastMCP's allowlists:```bash export FASTMCP_HTTP_ALLOWED_HOSTS="mcp.internal:8000" export FASTMCP_HTTP_ALLOWED_ORIGINS="https://my-client.internal" ``` The official Docker image already passes `--host 0.0.0.0`, so containers built from it work as before. See [`bm mcp`](https://docs.basicmemory.com/reference/cli-reference#bm-mcp). ### Client Treats a Refused Write as an Error **Problem:** After switching to the 1.0 tools, an agent or script reports a tool error from `bm_write` or `bm_edit`. **Cause:** Refused operations use MCP `isError`. In JSON mode, the payload has `error`, `message`, and an optional `try_instead`. Examples include `ALREADY_EXISTS` for a create that would overwrite a note, `REVISION_CONFLICT` for a failed checksum precondition, and `LOCKED` for a protected note. Do not expect legacy `NOTE_*` codes, `action: "conflict"`, or `currentChecksum` fields. **Solution:** Inspect the error code and message. For `ALREADY_EXISTS`, read the existing note and decide whether to edit it or deliberately replace it with `overwrite=True`. For `REVISION_CONFLICT`, read the current note again, reconcile your changes, and use the newly read checksum for the next guarded write. An `OUTCOME_UNKNOWN` error does not prove the write failed: read back the target before retrying. See [Migrating to 1.0](https://docs.basicmemory.com/reference/migrating-to-1-0) for the response contracts. `bm_edit(command="replace_section")` also refuses a missing exact heading. Give the heading in full, or use `command="append"` to add a new section. CLI `bm tool write-note` and `bm tool edit-note` retain their separate CLI contracts and exit with status `1` on refusal. ### MCP Endpoint Connection Fails (Cloud) **Problem:** Remote MCP connection not working. **Solutions:** 1. **Verify endpoint URL**: `https://cloud.basicmemory.com/mcp` 2. **Re-authenticate**:```bash bm cloud logout bm cloud login ``` 3. **Check authentication and connection status**:```bash bm cloud status ``` 4. **Restart your MCP client** (Claude Desktop, VS Code, etc.) --- ## Cloud Issues ### Cloud Mode Not Working **Problem:** CLI commands not working in cloud mode. **Solution:** ```bash bm cloud logout bm cloud login ``` ### Subscription Required Error **Problem:** "Active subscription required" message. **Solution:** 1. Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe?utm_source=docs&utm_medium=docs&utm_campaign=troubleshooting) 2. Complete subscription 3. Run `bm cloud login` again Access is immediate when subscription becomes active. ### Authentication Failed or Invalid Token **Problem:** Token expired or invalid. **Solution:** ```bash bm cloud logout bm cloud login ``` ### Rate Limited (HTTP 429) **Problem:** A cloud call fails with HTTP 429 (Too Many Requests). **Solution:** Basic Memory already retries a 429 that carries a valid `Retry-After` header, up to three attempts within 30 seconds, and `bm cloud push`/`pull` wait out the interval instead of aborting. If you still see the error, the limit outlasted that budget. Wait a minute and try again, or spread a large batch of writes over time. --- ## Indexing Issues ### Changes Not Indexing **Problem:** File changes not appearing in knowledge base. **Solutions:** 1. **Check index status**:```bash basic-memory status ``` 2. **Verify file permissions** - Ensure Basic Memory can read/write to the project directory 3. **Check .gitignore patterns** - Files matching ignore patterns are skipped 4. **Check the log for an unreadable directory** - Since v0.24, the file watcher logs a warning when it cannot read a new directory, naming the directory. This is common on Linux, where the watcher otherwise drops the error silently. Fix the directory's permissions, then index the project once:```bash bm project index ``` 5. **Rebuild the index** (or reset if issues persist):```bash basic-memory reindex # heavier: drop and rebuild the database basic-memory reset --reindex ``` Plain `basic-memory reset` only deletes the index — pass `--reindex` to rebuild it from your files. May take time for large knowledge bases. ### Duplicate Notes on macOS **Problem:** The same file appears twice — duplicate search results, `-1`-suffixed permalinks, or `bm_edit` failing on an affected note. Typically triggered by cross-platform sync tools that rewrite Unicode filename forms ([#1275](https://github.com/basicmachines-co/basic-memory/issues/1275)) or by case-only renames on case-insensitive APFS ([#1281](https://github.com/basicmachines-co/basic-memory/issues/1281)). **Solution:** v0.24 fixes case-only renames on case-insensitive filesystems: the rename sticks, and the next index pass removes the stale entry instead of leaving a ghost note. For duplicates left by an earlier version, or by a sync tool that rewrites Unicode filename forms, collapse them with a full rebuild: ```bash basic-memory reindex --full -p ``` Folder casing is handled separately: since v0.23.2, `bm_write` and `bm_move` reuses a uniquely matching existing folder regardless of case, preventing a new `schemas/` folder beside `Schemas/`. It does not repair existing duplicates. ### Ignored Files Still Show Up in Search **Problem:** You added a pattern to `.bmignore` or `.gitignore`, but notes that match it still appear in search results. **Cause:** Indexing skips ignored files, but it does not remove entries indexed before the pattern was added, because the files are still on disk. **Solution:** Preview and remove the stale index entries. Your files are left untouched: ```bash bm prune --dry-run bm prune ``` `bm prune` only touches the local index. `bm cloud prune` is different: it **deletes the matching files from cloud storage**, based on this machine's `.bmignore`, and works only on Personal workspaces. Preview before you delete: ```bash bm cloud prune --name --dry-run ``` ### Script Fails After a Note Read **Problem:** A script that reads notes with `bm tool read-note` now exits nonzero. **Cause:** Since v0.24, reading a note that does not exist exits with status `1` in every output mode, and JSON output carries `error: "NOTE_NOT_FOUND"`. Earlier versions exited `0` with null fields. **Solution:** Check the exit status instead of testing for null fields. ### `bm import document` Says "File not found" **Problem:** `bm import document notes/report.pdf` fails with "File not found" and shows a resolved path. **Cause:** Since v0.24, a relative path resolves against the project root, not your current directory, matching `bm ls` and `bm cat`. **Solution:** Pass the path relative to the project root, or an absolute path inside the project. Copy external files into the project first. Install the extractor for your file type, too: `basic-memory[pdf]` for PDF, `basic-memory[documents]` for Word and PowerPoint. ### Cloud Sync Issues **Problem:** Push or pull not working — setup errors, conflicts, or "no local sync path configured". The [Cloud Sync Guide's troubleshooting section](https://docs.basicmemory.com/cloud/cloud-sync#troubleshooting) owns the fixes: re-running setup, previewing transfers with `--dry-run`, resolving conflicts with `--on-conflict`, and configuring sync paths. --- ## Search and Content Issues ### Claude Can't Find Knowledge **Problem:** AI assistant not finding your notes. **Solutions:** 1. **Confirm files are in correct directory**:```bash basic-memory project list ls ~/basic-memory ``` 2. **Check frontmatter formatting** - Ensure YAML is valid:```yaml --- title: My Note tags: [tag1, tag2] --- ``` 3. **Use memory:// URLs for direct access**:```text memory://my-note-title ``` 4. **Rebuild the search index**:```bash basic-memory reindex ``` ### Entity Not Found **Problem:** Note doesn't exist at specified path. **Solutions:** 1. **Search for the note** — ask your AI assistant:```text Find notes about [topic] ``` 2. **Check exact title/permalink** - Titles are case-sensitive. If a `memory://` title URL matches more than one note, `bm_context` and `bm_read` refuse it; pass the permalink instead. 3. **List directory contents**:```text List files in [folder] ``` ### Semantic Search Unavailable (sqlite-vec Will Not Load) **Problem:** Vector or hybrid searches report that semantic search is unavailable, and the log says the Python build "does not support SQLite extension loading". **Cause:** Semantic search is always on in v0.24, but SQLite vector search needs the sqlite-vec extension. Some Python builds cannot load SQLite extensions. The most common one is the python.org installer on macOS, which `uvx` can pick up. Search then falls back to keyword-only. **Solution:** Reinstall Basic Memory under a Python that supports extension loading, such as uv-managed CPython, Homebrew Python, or the official Docker image: ```bash uv python install 3.13 uv tool install --python 3.13 --reinstall basic-memory ``` Then rebuild embeddings: ```bash bm reindex --embeddings ``` ### Embeddings Incomplete for Large Notes **Problem:** Parts of a very large note don't show up in semantic search. **Cause:** Vector sync embeds at most 256 chunks of one note per pass and defers the rest. Local projects finish those notes on later index passes. **Solution:** Run `bm reindex --embeddings`. As of v0.24 it repeats passes until no deferred chunks remain. If it stops making progress, it reports how many notes still have pending chunks and exits nonzero. --- ## Performance Issues ### Slow Operations **Problem:** Commands or syncing taking too long. **Solutions:** 1. **Check knowledge base statistics**:```bash basic-memory project info main ``` 2. **Archive old content** - Move inactive notes to archive folder 3. **Coalesce rapid file saves** - Increase the index delay when an editor writes the same file repeatedly in a short burst:```bash bm config set index_delay 2000 ``` 4. **Tune concurrent accepted writes carefully** - For workloads that submit many local writes at once, increase materialization workers from the default of `4`:```bash bm config set materialization_workers 8 ```
This affects local write materialization, not general indexing concurrency. ### High Memory Usage **Problem:** Basic Memory using too much memory. **Solutions:** 1. **Limit context depth** in MCP calls (use `depth=1` or `depth=2`) 2. **Reduce search page size** 3. **Archive old content** --- ## Installation Issues ### FastAPI Import Error After Installing v0.24.0 **Problem:** On a fresh v0.24.0 install, `bm status` and other commands fail with: ```text cannot import name 'get_flat_dependant' from 'fastapi.dependencies.utils' ``` **Cause:** v0.24.0 allowed any FastAPI from 0.136.1 up, and newer FastAPI releases removed a helper Basic Memory imports. **Solution:** Upgrade to v0.24.1 or later, which pins FastAPI to 0.139.0: ```bash uv tool upgrade basic-memory ``` If you must stay on v0.24.0, pin FastAPI yourself: ```bash uv tool install basic-memory --with 'fastapi==0.139.0' ``` ### Python Version Error **Problem:** Unsupported Python version error. **Solution:** Install Python 3.12 or higher: ```bash # macOS with Homebrew brew install python@3.13 # Or use pyenv pyenv install 3.13.0 pyenv global 3.13.0 ``` ### uv Not Found **Problem:** `uv` command not found. **Solution:** Install uv: ```bash # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Then add to PATH (restart terminal or run) source ~/.bashrc # or ~/.zshrc ``` ### Permission Errors **Problem:** Can't create files or access directories. **Solutions:** 1. **Check directory permissions**:```bash ls -la ~/basic-memory ``` 2. **Fix permissions**:```bash chmod -R u+rw ~/basic-memory ``` 3. **Ensure Claude Desktop can execute uvx** --- ## Project Issues ### Project Not Found **Problem:** Project doesn't exist in configuration. **Solutions:** 1. **List available projects**:```bash basic-memory project list ``` 2. **Add the project**:```bash basic-memory project add my-project ~/path/to/project ``` ### Cloud Project Removal Deleted Its Cloud Files **Problem:** `bm project remove` on a cloud project deleted its files from cloud storage. **Cause:** Since v0.24, removing a cloud-routed project always deletes its cloud files. The command warns and asks for confirmation unless you pass `--yes`. **Solution:** Restore from a cloud snapshot (`bm cloud snapshot list`, then `bm cloud restore`). Your local sync directory is kept unless you passed `--delete-local-files`. Take a snapshot before removing a project you might need again. ### Project Not Configured for Sync (Cloud) **Problem:** "Project has no local_sync_path configured" **Solution:** ```bash bm cloud sync-setup research ~/Documents/research bm cloud pull --name research ``` ### Moving Notes Between Projects **Problem:** Can't move notes from one project to another. **Current solution:** Copy the file manually or create a new note in the destination project, then delete the original. --- ## Configuration Issues ### Config Changes Not Taking Effect **Problem:** Updated config.json but nothing changed. **Solutions:** 1. **Restart your MCP client** (Claude Desktop, VS Code, etc.) after changing configuration. 2. **Check for an environment override** - a `BASIC_MEMORY_*` variable wins over `config.json`. `bm config list` marks overridden settings, and the `basic_memory_diagnostics` MCP tool lists the overriding variables (redacted). 3. **Look for values an older version persisted** - before v0.24, any config save wrote one-off environment overrides into `config.json` permanently. v0.24 no longer does this, but values written earlier stay until you remove them:```bash bm config unset ``` ### Removed Settings Have No Effect **Problem:** `semantic_search_enabled: false` or `disable_permalinks: true` in `config.json` is ignored. **Cause:** Both settings were removed in v0.24. Semantic search is always on, and Markdown notes always get a permalink. Old values are ignored rather than rejected. See [Configuration](https://docs.basicmemory.com/reference/configuration#v024-changes). ### Project Name Refused Under `BASIC_MEMORY_PROJECT_ROOT` **Problem:** Adding a project such as `Research/2026` fails when `BASIC_MEMORY_PROJECT_ROOT` is set (for example in Docker). **Cause:** Since v0.24, a project name whose permalink contains `/` is refused under a project root, so each project stays one top-level directory. **Solution:** Use a single-segment name, such as `research-2026`. ### Invalid JSON in Config **Problem:** Configuration file has syntax errors. **Solution:** Validate your JSON: ```bash cat ~/.basic-memory/config.json | python -m json.tool ``` Common issues: - Missing commas between properties - Trailing commas after last property - Unquoted strings --- ## Database Issues ### Database Locked **Problem:** "database is locked" error. **Solutions:** 1. **Close other applications** accessing the database 2. **Restart Basic Memory**:```bash # Find and kill processes pkill -f "basic-memory" ``` 3. **Clean up SQLite WAL/shared-memory files** — after closing all clients, the supported path is:```bash basic-memory reset --reindex ```
(It removes `memory.db-shm`/`memory.db-wal` itself — deleting the `-wal` file by hand can silently discard recently indexed changes.) ### Corrupted Database **Problem:** Database errors or inconsistent state. **Solution:** Reset and re-index: ```bash basic-memory reset --reindex ``` With `--reindex`, the index is rebuilt from your markdown files. All files are preserved. --- ## Getting Help ### Check Logs ```bash # View the log file (Windows uses per-process basic-memory-.log names) cat ~/.basic-memory/basic-memory.log # For cloud connection diagnostics bm cloud status ``` ### Command Help ```bash # View all commands basic-memory --help # Get help for specific commands basic-memory status --help basic-memory project --help bm cloud --help # Read the bundled manual bm man list bm man search-notes ``` ### Community Support - **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel - **GitHub Issues**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues) --- ## Next Steps Installation guide and initial setup. Complete command documentation. Cloud sync configuration and troubleshooting. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.