# Errors

> Every MMW server error and notice text — what it means and what to do.

On this page you will learn what MMW errors look like, what each text means and how to fix it. Texts are quoted verbatim, so you can search the page for them (Ctrl+F).

## How errors arrive

```text
  HTTP request ──► key check ──► 401 if the key is not accepted
                       │
                       ▼
                 tool call ──► response with "isError": true and the reason text
```

- **Authentication errors**: HTTP status `401`, before any tool runs.
- **Tool errors**: a normal JSON-RPC response with `"isError": true`. For the memory tools the text reads `Error executing tool search: …`; the tables below show the part after the colon.
- **Subscription notices** start with `[MMW Notice]:`; show them to the person as they are.

There is no separate HTTP `429` status: exceeding the call limit comes back as a tool error with `MCP rate limit exceeded` or `project call limit exceeded`.

## Authentication and account

| Response | Meaning | What to do |
| --- | --- | --- |
| HTTP `401` | No `Authorization` header; the key is wrong, revoked or expired; the OAuth token was issued for another server; or the account was suspended by the operator. | Check the key in the client config (`MMW_API_KEY` or `Authorization: Bearer mmw_…`). Issue a new key in your account if needed. For claude.ai, reconnect the connector. |
| `account is unavailable` | The account is switched off (not active). | Contact support. |
| `[MMW Notice]: This MMW account has no active subscription, so memory is unavailable. The account owner can manage it in their MMW account settings.` | No active subscription: memory can be neither read nor written. | The account owner activates a plan in the account. For an organization, contact us. |
| `[MMW Notice]: The MMW subscription has expired. Memory is read-only during the grace period; saved memories can still be searched.` | The subscription expired and the grace period is running: `search`, `validate_memory` and `gateway_call` work, `remember` and `forget` do not. | Renew the subscription to save again. |
| `[MMW Notice]: This MMW account is suspended because its subscription expired. The account owner can manage it in their MMW account settings.` | The grace period ended and the account is suspended. | The account owner renews the subscription in the account. |
| `membership may not write in this organization` | In an organization: you have the auditor role, or your membership is inactive (offboarded, contractor term expired). | Contact the organization admin. Check the space switcher in your account. |

## Limits

| Text | Meaning | What to do |
| --- | --- | --- |
| `MCP rate limit exceeded` | The account-wide request limit for a sliding 60-second window was exceeded. | Wait a minute; call less often. |
| `project call limit exceeded` | The project's per-minute plan call limit was exceeded. | Wait a minute or upgrade the plan. |
| `project gateway concurrency limit exceeded` | Too many concurrent integration calls. | Make `gateway_call` calls one after another. |
| `project memory limit exceeded` | The project's plan record limit is reached. | Delete what you no longer need with `forget`, or upgrade. Reading keeps working. |
| `maximum number of memories exceeded for workspace` | The technical record limit of the workspace is reached. | Save to another workspace or delete unneeded records. |
| `maximum number of memories exceeded for tenant` | The technical record limit of the account is reached. | Delete unneeded records or contact support. |

## Workspaces and projects

| Text | Meaning | What to do |
| --- | --- | --- |
| `workspace '…' is not active` | `search`: no such workspace (nothing was saved in it yet) or it was deleted. | Check the `workspace` name. A workspace is created by the first `remember`. |
| `workspace '…' was deleted and cannot be reused` | A workspace with this name was deleted; the name cannot be taken again. | Use another name. |
| `403 Forbidden: workspace access denied for project` | The workspace belongs to another project than the key's. | Use the right project's key or another workspace name. |
| `bound project is missing, inactive, or outside tenant` | The key's project was deleted or is inactive. | Issue a key for an active project. |

## remember

| Text | Meaning | What to do |
| --- | --- | --- |
| `content must not be empty` | Empty text. | Pass a non-empty `content`. |
| `content exceeds maximum allowed length` | Text longer than 100,000 characters. | Split it into several records. |
| `Memory rejected by Security Guard: Memory poisoning detected: matching pattern '…'` | Memory Guard found an instruction that looks like a memory-poisoning attempt (for example "ignore previous instructions"). | Rephrase the record; do not store instructions aimed at future agents. |
| `workspace and scope must not be empty` | Empty `workspace` or `scope`. | Do not send empty strings; use the defaults. |
| `confidence must be between 0 and 1` | `confidence` out of range. | Pass a number from 0 to 1. |
| `source_id is required when source_hash is provided` | A hash without a source. | Add `source_id`. |
| `derived_from accepts at most 50 memory ids` | More than 50 IDs. | Build intermediate summaries. |
| `derived_from contains unknown memory ids` | Some IDs do not exist, were deleted or are not visible to you. | Take IDs from a fresh `search`. |
| `invalid X-Idempotency-Key` | The key is empty, longer than 256 characters, or has invalid characters. | Use 1–256 printable ASCII characters without spaces, such as a UUID. |
| `409 Conflict: idempotency key was used with different input` | The same idempotency key was already used with other parameters. | Use a new key for a new record. |

## forget, validate_memory

| Text | Meaning | What to do |
| --- | --- | --- |
| `Either memory_id or source_id must be provided` | `forget` without `memory_id` or `source_id`. | Pass one of them. |
| `source_id and current_source_hash are required` | `validate_memory` without a source or hash. | Pass both. |

## gateway_call and integrations

| Text | Meaning | What to do |
| --- | --- | --- |
| `invalid gateway server or tool name` | Empty name or a dot in `server`/`tool`. | `server: "github_readonly"`, `tool: "get_file_contents"`, separately. |
| `gateway project not found` | `project_id` does not exist or is inactive. | Omit `project_id` or pass an active project. |
| `gateway tool not found` | The tool is not among the project's enabled, healthy integrations. | Check the integration in your account, "MCP gateway" section. |
| `required downstream secret is missing` | The integration has no token configured. | Add the integration secret in your account. |
| `downstream tool is not allowlisted` | The tool is not allowed for this integration. | Use tools from the `tools/list` result. |
| `downstream timeout` | The integration did not answer in time. | Retry later. |
| `downstream response size limit exceeded` | The integration's response is too large. | Narrow the request (for example a file path instead of a directory). |
| `downstream transport failure`, `downstream JSON-RPC error`, `downstream returned malformed JSON-RPC` | Failure on the integration side. | Retry later; if it persists, contact support. |
| `unknown MCP tool` | A tool that is not in the list was called (including `gateway_call` on a ChatGPT connection). | Call `tools/list` and use the names it returns. |

## Local agent mmw-agent

| Text | Meaning | What to do |
| --- | --- | --- |
| `MMW rejected the API key (check MMW_API_KEY in the MCP config)` | The server answered 401/403. | Check `MMW_API_KEY`. |
| `MMW server unreachable: …` | No connection to the server. | Check the network and `MMW_ENDPOINT`. |
| `MMW_API_KEY is not set. …` | The agent started without a key. | Add `MMW_API_KEY` to the `env` of the MCP config. |

Session history sync errors (such as running out of plan storage) show up in [`mmw_sync_status`](/reference/mmw-sync-status/) and are covered in [Agent troubleshooting](/agent/troubleshooting/).

When contacting [support](/account/support/) (support@mmwhub.tech), include the exact error text, the time and the tool name. Never send keys or memory content.

## Next steps