Troubleshooting and FAQ

Last updated Oct 11, 2026100% grounded

Overview

This guide helps you resolve common setup challenges, missing or invalid API keys, search mismatches, and upgrade or configuration issues when working with Mem0. Follow the troubleshooting steps and frequently asked questions below to get your memory integration running smoothly.

Note

If you encounter unexpected behavior, running your built-in environment diagnostics or doctor check is the fastest way to identify missing credentials, incompatible package versions, or connection failures.

Setup and Installation Issues

Version Incompatibilities and Missing Dependencies

If you encounter errors during startup or package initialization, your installed client version may not meet the minimum requirement.

Important

Ensure you are running mem0ai>=2.0.10. To update your Python package to the required version, run:

uv pip install --python $(which python) "mem0ai>=2.0.10"

Local Infrastructure Checks for Open Source Mode

When running in open source mode with local vector stores or language models, connectivity issues are common if underlying services are not running or reachable.

Tip

Use the configuration wizard or manually verify that your local service ports are active:

Ollama: Ensure it is running at http://localhost:11434 (run ollama serve if stopped).
Qdrant: Ensure your vector database container is running and reachable at http://localhost:6333.
PGVector: Verify that PostgreSQL with the pgvector extension is active on port 5432.

API Key Troubleshooting

Missing or Unsynchronized Keys

If your memory operations fail with authentication errors, your API key may be missing from your environment variables, configuration files, or ecosystem touchpoints.

Verify your environment variable: Ensure MEM0_API_KEY is exported in your shell or configuration file.
Sync your key across tools: Propagate your active API key into supported ecosystem configuration files and shell profiles (~/.zshrc, ~/.bashrc, ~/.bash_profile, or Claude settings) to prevent mismatch errors between your command-line setup and background plugins.

Error Type	Common Cause	Resolution
`401 Unauthorized`	Expired or malformed API key	Re-authenticate or update your `MEM0_API_KEY` variable.
`API key missing`	Variable not exported in current shell	Set `MEM0_API_KEY` or run setup again.
`Wildcard Scope Refusal`	Configured user ID evaluates to a wildcard	Provide a specific, non-wildcard user identifier.

Search and Filtering Mismatches

Entity Scoping and Metadata Filters

Mem0 requires entity parameters (such as user_id, agent_id, app_id, and run_id) to be passed inside structured filters rather than as top-level parameters in newer versions.

Warning

Passing scoping parameters at the top level during search or listing operations can result in empty result sets or search mismatches. Always nest scoping identifiers inside your query filters:

{
  "filters": {
    "user_id": "your-user-id",
    "app_id": "your-repo-app-id"
  }
}

Hybrid and Keyword Search Fallbacks

If hybrid or keyword searches fail or return unexpected results, check your database capabilities:

Qdrant: Server-side sparse vectors and BM25 hybrid search require Qdrant >= 1.15.2 with inference enabled. If an incompatible server version rejects the payload, Mem0 automatically falls back to dense-only vector search to prevent data write failures.

Frequently Asked Questions

How do I check the health of my installation?

You can execute diagnostic checks to inspect your Python version, data directory permissions, API key presence, and remote authentication status in real time. A successful check verifies that all connection parameters and environment variables are properly aligned.

What should I do if my memory deletion or forget request fails?

Ensure that your user and repository scopes are explicitly defined and are not wildcards. The system refuses wildcard deletion requests to prevent accidental data loss across shared environments.

How do I switch between Platform and Open Source modes?

You can re-run your setup configuration command with your preferred mode flag to re-configure your storage backends, API endpoints, and provider credentials.

Was this page helpful?

Workflow Tool Connectors