# Troubleshooting Reviewed 2026-11-06 against v12.6.0 and current GitHub main. Python 3.11+ is required. Start with the exact failing operation and deployment. Keep the error message, service version, backend, client, endpoint and relevant log lines. Remove API keys, tokens and private memory content before sharing diagnostics. ## Service does not start ```bash memory server --help memory info memory logs -n 50 ``` Check Python 3.11+, the environment containing the installed package, configured database/model paths and permissions, and whether another process already owns the intended port. `memory info` and `memory logs` inspect the CLI-managed local HTTP service; use your service manager's logs for systemd, containers or another host. For foreground local diagnosis, start the service with its normal environment: ```bash memory server --http ``` Do not start a second process on the same port. Starting the foreground server alone does not configure remote authentication or HTTPS. Use the [production guide](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/deployment/production-guide.md) for deployed services. ## HTTP connection or authentication fails The default local HTTP URL is `http://127.0.0.1:8000`. Use the actual deployed URL and credentials: ```bash MEMORY_BASE_URL=http://127.0.0.1:8000 MEMORY_API_KEY=replace-with-your-api-key curl --fail "$MEMORY_BASE_URL/api/health" \ -H "X-API-Key: $MEMORY_API_KEY" ``` | Symptom | Check | |---|---| | Connection refused or timeout | Correct host/port, running service, bind address, proxy and network reachability. | | TLS handshake or certificate error | Whether that endpoint actually serves HTTPS, certificate hostname/expiry and the client's trusted CA chain. | | 401 | Whether the deployed API key or OAuth access token reaches the server. | | 403 | Required read/write scope, store restrictions and the server's access rules. | | 404 | Endpoint path and reverse-proxy routing; compare with the running server's `/api/docs`. | Do not solve certificate failures by globally disabling TLS checks. For a private CA, provision trust on the client. See [Remote MCP Setup](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md). ## MCP client has no memory tools - For stdio, verify the client can execute the configured `memory server` command; a desktop app may have a different PATH from your shell. - For remote MCP, connect to the configured authenticated `/mcp` endpoint, not `/api/search` or the dashboard URL. - Restart the client after configuration changes and complete its authentication flow. - Use current tool names such as `memory_store`, `memory_search` and `memory_quality`; old aliases were removed in v11. See [Integration Guide](03-Integration-Guide) and the [migration mapping](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/MIGRATION.md). ## Search finds no memories Distinguish missing data from excluded data. Check the target store, tags, time filters, superseded state and permissions before relaxing the query. For REST, use `n_results`; for MCP, use `limit`. Arguments for `memory_search`: ```json {"query": "authentication", "limit": 5, "include_debug": true} ``` If a memory exists but is absent from semantic search, inspect embedding/model errors and migration state. Do not force a new embedding model against existing vectors. A model fallback is not proof of equivalent retrieval. ## Hooks do not inject context Verify that only the intended plugin or legacy hooks installation is active. Check the hooks process's endpoint, credentials and project detection, then inspect its own logs. An empty database or strict filters can legitimately produce no context. Use [Quality Hooks Integration](17-Quality-Hooks-Integration) for current installation paths. Do not rely on an old `test-hooks.js` command copied from an earlier release. ## Quality scores look wrong Check `quality_provider`, `quality_components`, `computed_quality` and `user_rating`. A fallback to implicit signals can produce a valid number without running the requested model; a human rating can keep the effective score fixed after rescoring. See [Quality System](14-Memory-Quality-System-Guide) and [ONNX Evaluation](15-ONNX-Quality-Evaluation). ## Database locked, slow requests or growing memory use Inspect active service processes, long-running transactions, concurrency, model initialization and logs. Stop duplicate writers through their service manager. Do not delete database, WAL or SHM files to clear an error. Back up before repair, migration or cleanup. Use [Performance Optimization](05-Performance-Optimization) to measure the cause. Scheduled consolidation, optional ML work and sync traffic can compete with foreground requests; inspect their status rather than assuming a storage-only problem. ## Sync does not converge Check which mechanism is configured: Hybrid secondary synchronization or delta event-log sync. They have separate configuration and status. Verify peer URL/authentication, embedding-model agreement, errors and progress over more than one cycle. The [self-hosted sync hub guide](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/self-hosted-sync-hub.md) explains the topology and delta-sync dashboard panel. Do not treat a successful local write or HTTP health response as proof that another node has received the change. ## Import, export and maintenance Use the current repository scripts and inspect their help before touching data: ```bash # From a repository checkout, using its configured Python environment python scripts/sync/export_memories.py --help python scripts/sync/import_memories.py --help ``` These scripts target local SQLite-vec data; they are not a universal cross-backend or full graph/identity backup. Check the documented fields and destination, preserve a backup, and validate the imported result before replacing the source. See the [migration guide](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/migration.md). ## Report a reproducible problem Search [existing issues](https://github.com/doobidoo/mcp-memory-service/issues), then include version, backend, deployment method, client, sanitized configuration, minimal steps, expected/actual behavior and relevant logs. For ranking problems, include representative queries and safe sample memories, not only a screenshot of the result count. Historical troubleshooting cases remain in the [page history](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING/_history).