---
title: "Troubleshooting and FAQ"
description: "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 an..."
last_updated: "2026-10-11T17:38:36.488526+00:00"
canonical_url: "https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/troubleshooting/troubleshooting-and-faq"
---

## 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:
> ```bash
> 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.

1. **Verify your environment variable:** Ensure `MEM0_API_KEY` is exported in your shell or configuration file.
2. **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:
> ```json
> {
>   "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.

## Related

- [Quickstart Overview](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/getting-started/quickstart-overview)
- [Command Line Setup](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/getting-started/command-line-setup)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/llms.txt) for all pages in this wiki.