# Agent troubleshooting

> Symptom, cause and fix for common mmw-agent problems, based on how the agent actually behaves.

This page helps you find out quickly what is broken: the client connection, the key, the server or session sync. Each section is symptom, cause, fix.

The first step is nearly always the same: run `status` in a terminal **with the same variables** as in your client config.

```bash
MMW_API_KEY=mmw_your_key MMW_ENDPOINT=https://mcp.mmwhub.tech \
  uvx --from https://app.mmwhub.tech/downloads/mmw-agent/mmw_agent-0.1.4-py3-none-any.whl mmw-agent status
```

## MMW tools do not appear in the client

**Cause 1: no `uvx` or a suitable Python.** The agent needs Python 3.11 or newer and is started through `uv`.

**Fix:** install [uv](https://docs.astral.sh/uv/), check `uvx --version` in the same environment the client runs in, and restart the client. GUI clients (Claude Desktop) sometimes do not see your terminal's `PATH`; in that case put the full path to `uvx` in `command`.

**Cause 2: no key.** The agent exits immediately with "MMW_API_KEY is not set. Copy the key from your MMW account and put it in the MCP config." The client reports that the server failed to start.

**Fix:** add `MMW_API_KEY` to the config's `env` block (not to your shell profile — the client may not read it).

**Cause 3: the client was not restarted.** The client asks for the tool list when it launches the agent.

**Fix:** fully restart the client after editing the config.

## Only `mmw_sync_status` is listed and the server is called "MMW (offline, local agent)"

**Cause:** the MMW server was unreachable when the client started (no network, a proxy, a server restart). The agent answered the client itself so it would not fail, and offered only the local tool.

**Fix:** check your network and `status`. The agent retries on every later call, but many clients cache the tool list at start-up — restart the client once the server is reachable.

## A tool call returns "MMW server unreachable: …"

**Cause:** the agent could not send the request (network, DNS, timeout).

**Fix:** try again later and check the address in `MMW_ENDPOINT`. Session sync loses nothing meanwhile — it catches up automatically.

## "MMW rejected the API key (check MMW_API_KEY in the MCP config)"

**Cause:** the server answered 401 or 403 — no key, or the key was revoked, expired or copied incompletely. In an organization, your access may have ended (you left, or a contractor term expired).

**Fix:** copy the key again or issue a new one in your account — see [API keys and OAuth](/account/api-keys-and-oauth/). A key is shown once; if you lost it you cannot view it again, only issue a new one.

The same cause is behind `ServerError: 401 …` printed by `mmw-agent status` or `mmw-agent sync`.

## Tools work, but the server talks about a subscription

`[MMW Notice]: …` messages come from the server, not the agent:

| Message | Meaning |
| --- | --- |
| …has no active subscription, so memory is unavailable | No active subscription; memory is unavailable. |
| …subscription has expired. Memory is read-only during the grace period | Grace period: read-only — `search` works, `remember` does not. |
| …account is suspended | The account is suspended because the subscription expired. |

**Fix:** renew your plan in your account — [Plans and billing](/account/plans-and-billing/). Other server errors are in the [errors reference](/reference/errors/).

## `consent` says "Consent must be given by a person in an interactive terminal"

**Cause:** the command was run outside an interactive terminal — from a script, CI, an IDE task, or by a model. That is by design: a program cannot give consent.

**Fix:** open a regular terminal and run `mmw-agent consent` yourself.

## `consent` says "No Claude Code or Codex sessions found on this computer"

**Cause:** the agent looks in `~/.claude/projects/*/*.jsonl` and `~/.codex/sessions/**/*.jsonl`. There are no sessions there, or your clients keep them under a different home directory (for example, another user).

**Fix:** work in Claude Code or Codex so sessions exist, or point `MMW_SESSIONS_HOME` at the right directory — in both the terminal and the client config.

## Consent was given, but `last_cycle.state` is `consent_required`

**Cause:** the terminal and the client use different state directories, for example `MMW_AGENT_HOME` or `MMW_SESSIONS_HOME` is set in the client config but not in the terminal.

**Fix:** run `consent` with the same variables as the client config. The receipt is `agent.json` inside `MMW_AGENT_HOME` (default `~/.mmw`).

## Codex (or Claude Code) sessions are not uploaded

**Cause:** consent covers only the clients whose sessions were on disk when you ran `consent`. If you started using Codex later, its sessions are not covered.

**Fix:** run `mmw-agent consent` again; the agent shows the updated client list.

## Nothing is uploaded although consent is in place

Ask the assistant for the sync status (the `mmw_sync_status` tool) and look at `last_cycle`:

| `state` | Cause | What to do |
| --- | --- | --- |
| `idle` | The agent just started; no cycle yet. | Wait up to a minute. |
| `offline` | The server is unreachable; the pause between attempts grows up to 5 minutes. | Nothing: the agent catches up on its own. |
| `server_busy` | The server is temporarily low on space and accepted nothing. | Nothing: the agent retries in 5 minutes; the data stays on your disk. |
| `quota_exceeded` | The plan's history volume is used up (`used_bytes`, `max_bytes`). | Change plan, or accept that new sessions are not uploaded. |
| `unsupported` | The server has no session sync. | Check `MMW_ENDPOINT`. |
| `error` | Unexpected error; details in the `error` field. | The agent retries; if it persists, contact [support](/account/support/). |
| `ok` | The cycle completed. | See the counters below. |

Counters when the state is `ok`:

- `skipped_by_plan_history` — sessions older than your plan's history depth; skipped on purpose;
- `conflicts` — files the server already accepted in a different form; the agent skips them;
- `truncated` — files that became shorter than the accepted part (rewritten or truncated); the agent leaves them alone.

Remember that sync runs only while the agent is running, that is, while the client is open. For a one-off cycle: `mmw-agent sync`.

## `revoke` says "Local consent removed; server not notified"

**Cause:** the server was unreachable when you revoked.

**Fix:** uploads are already stopped — there is no local receipt. Run `mmw-agent revoke` again once you are online so the server also unregisters the device.

## Agent hints are in the wrong language

**Cause:** the language follows the server address. If `MMW_ENDPOINT` is not set, the agent uses its regional default and a different language.

**Fix:** set `MMW_ENDPOINT=https://mcp.mmwhub.tech`, or force the language with `MMW_LANG=en`.

When you contact support, include the `mmw-agent status` output and the time of the error. Do not send your key or memory contents: `status` does not print them, but your config files do contain the key.

## Where next