The failures people run into, what causes each one, and the fix. If you have an error code, search this page for it first.

## Read the body, not just the status

> [!IMPORTANT]
> A tool that fails still returns HTTP 200. Scope problems, missing files, edit conflicts and shell refusals all arrive as a 200 response whose envelope carries an error.

```json nocopy
{ "content": [{ "type": "text", "text": "{\"error\":{\"code\":\"INSUFFICIENT_SCOPE\",\"message\":\"...\"}}" }] }
```

Only auth and routing problems use HTTP status codes. If your client only checks `response.ok`, it will treat half of these failures as success. Parse `content[0].text` and look for `error.code` every time.

## Authentication

| Symptom | What it is | Fix |
|---|---|---|
| `401` `UNAUTHORIZED`, "Missing or invalid Authorization header" | The header is absent or not shaped `Bearer mk_...` | Send `Authorization: Bearer mk_...` |
| `401` `UNAUTHORIZED`, "Invalid or expired API key" | The key does not match a live key. A truncated, wrapped or quoted key fails here. An `mk_` key is exactly 35 characters | Re-mint the key at `/api-keys` and store it without reformatting |
| Everything 401s even though the key is definitely right | You are calling the apex domain. It redirects, and the redirect strips your `Authorization` header | Always use `https://www.monofile.ai` |
| `403` `ORG_MISMATCH`, "Workspace mismatch" | You sent an `X-Monofile-Org-Id` header that disagrees with the workspace your credential belongs to | Drop the header. A key already carries its own workspace, and no header can change it |
| `200` with `INSUFFICIENT_SCOPE`, "Missing required scopes: ..." | The key is valid but lacks a scope the tool needs | Mint a key with the scopes listed in the message. See [[Scopes]] |

## Shell commands

| Symptom | What it is | Fix |
|---|---|---|
| `SANDBOX_NOT_ENTITLED` | The command needs the full shell, which is part of the paid plans: Pro for a personal workspace, Team for an organization | Upgrade, or stay inside the built-in commands, which keep working on every plan |
| "pipes are not supported in this environment" with exit code 2 | The built-in shell refuses operators it cannot honour. The same applies to `<`, `2>`, backticks, `$(...)` and background `&` | Use command flags instead, for example `grep -n "pattern" /path`, or move to the full shell |
| `SANDBOX_BUSY` | One command runs per workspace at a time | Wait and retry. This is expected under concurrency |
| `RATE_LIMITED`, "Daily sandbox limit reached" | You have used the day's allowance of full-shell commands | Wait for the window, or use read-only commands, which are not capped |
| `INSUFFICIENT_CREDITS` | The full shell is per-use compute billed against AI credits | Wait for the next billing period, or top up |
| `INSUFFICIENT_SCOPE`, "The sandbox was restored and nothing was written" | Scopes apply to what the command changed, not to the command text. The whole set of changes was rejected together | Use a key with `files:write`, or `files:delete` for removals |
| `OUT_OF_FOLDER_SCOPE` | A folder-restricted key changed files outside its folder | Keep the command's writes inside the folder |
| `DIFF_TOO_LARGE` | The command changed more than 200 files, so nothing was written | Split it into several smaller commands |
| `TIMEOUT` | The command exceeded its timeout, 60 s by default | Pass a longer `timeout`, up to 240 s. Changes made before the timeout are still written back |

More in [[File and Shell Tools]], and the numbers in [[Limits]].

## Editing files

| Symptom | What it is | Fix |
|---|---|---|
| `NO_MATCH`, "The text to replace was not found" | `old_string` does not appear in the file, usually because you retyped it instead of copying it | Read the file again and copy `old_string` verbatim from that output |
| `MULTIPLE_MATCHES`, "Found N occurrences" | The text appears more than once and the edit would be ambiguous | Include more surrounding context, or pass `replace_all: true` |
| `EDIT_CONFLICT`, "File was modified at ..." | Someone or something else wrote the file after you read it | Read it again, then retry the edit against the new content |
| `INVALID_INPUT`, "Cannot read a folder" | The path is a folder | Use `bash ls` or `bash tree` for folders |
| `FILE_NOT_FOUND` | The path does not exist, or a parent folder does not | Check with `bash ls`. `write` creates parent folders for you by default |
| `IS_DIRECTORY` on `create_share_link` | Share links are per file | Use `share_folder` for a folder. See [[Public Folders]] |

## Reverting

| Symptom | What it is | Fix |
|---|---|---|
| `CONFLICT`, "Files were modified after this changeset" | A newer write landed on a file the changeset touched, so reverting would discard it silently | Inspect the newer version, then pass `force` if you still want the revert |
| `CHANGESET_NOT_FOUND` or `VERSION_NOT_FOUND` | The id is wrong or belongs to another workspace | List them first with `list_changesets` or `list_versions` |
| `CAP_EXCEEDED` on `checkpoint` | Either the file already has 10 checkpoints, or the folder holds more than 200 files | Reuse or remove an old checkpoint, or checkpoint a smaller subfolder |

## The AI assistant

All three of these are `403` with code `ACCESS_DENIED`, distinguished by `reason`:

| `reason` | What it is | Fix |
|---|---|---|
| `no_subscription` | The assistant needs the Pro plan | Subscribe to Pro |
| `no_credits` | You have spent this period's AI credits | They reset at the start of the next billing cycle |
| `org_plan_required` | You are in an organization workspace, and AI there is billed to the organization | An organization admin subscribes to Team, or switch back to your personal workspace to use your own Pro plan |

More in [[AI Credits and Usage]].

## The CLI

| Symptom | What it is | Fix |
|---|---|---|
| `Not logged in to <origin>`, exit code 3 | The CLI stores credentials per API origin, so a login against one environment does not authenticate another | `monofile login` for that origin, or set `MONOFILE_API_KEY` |
| `monofile login` hangs and then times out, with "Failed to fetch" in the browser console | Recent Chromium versions require permission before an `https` page may reach a loopback server, and headless browsers deny it automatically | Click Allow when prompted. Headless: `monofile login --no-browser` and open the printed URL, or pipe an existing key into `monofile login --with-key` |
| `monofile api GET /api/users/me` complains about a path like `C:/Program Files/Git/api/users/me` | Git Bash and other MSYS shells rewrite Unix-looking arguments before the CLI ever sees them | Use `//api/users/me`, or set `MSYS_NO_PATHCONV=1` |
| Every command fails with "is not valid JSON" | A hand-edited or truncated config or credentials file | Delete the named file and log in again |
| `monofile grep` exits 1 with no output | Zero matches is a non-zero exit, as in Unix `grep` | Treat exit 1 from `grep` as "no match" |
| `monofile sync` reports the folder is locked, exit code 6 | One sync per folder at a time | Wait for the other run to finish. The CLI clears a lock left behind by a dead process |
| "Not a Monofile folder" or "was cloned from a different origin", exit code 2 | The directory has no sync state, or its state points at another environment | `monofile clone` it, or point the CLI at the origin it was cloned from |

Exit codes are a stable contract: `0` ok, `1` error, `2` usage, `3` auth, `4` not found, `5` forbidden, `6` conflict, `7` network. More in [[CLI Commands]].

## Installing a fresh release

If `npx @monofile/cli` cannot find a version you know exists, the cause is almost always local. A stale npm cache is the usual one, and a `min-release-age` setting in your npm configuration also hides any release newer than its threshold.

```bash title="Terminal"
npm cache clean --force
npx --min-release-age=0 -y @monofile/cli@latest --version
```

## MCP clients

| Symptom | What it is | Fix |
|---|---|---|
| The server starts but every tool call returns `UNAUTHORIZED` | The stdio server starts even with no key, and says so on stderr | Pass the key: `-e MONOFILE_MCP_API_KEY=mk_...`, or an `env` block in the client config |
| The hosted endpoint returns `401` "Unauthorized: Invalid or missing API key" | A missing or malformed bearer header, or the apex domain again | `Authorization: Bearer mk_...` against `https://www.monofile.ai/api/mcp` |
| The hosted endpoint returns `405` "Method not allowed. This server operates in stateless mode" | The client opened a `GET` for a server-sent-event stream. The endpoint is stateless and POST-only | Use a client that speaks POST Streamable HTTP, or switch to the stdio server |
| A tool you can call over REST is missing from the client's tool list | The hosted endpoint advertises only the tools your key's scopes allow. A key minted without an explicit scope list gets a narrow default, which hides sharing, social and search tools | Mint the key with an explicit scope list. `GET /api/tools` is unfiltered, so a difference between the two is always a scope gap |
| The stdio server reports an unknown tool the API clearly has | The stdio server lists a snapshot taken when it was published, so it can lag the live registry | Upgrade `@monofile/mcp`, or use the hosted endpoint |
| Tools work but touch the wrong environment's data | The server defaults to production when no API URL is set | Set `MONOFILE_API_URL` |

More in [[Connecting MCP Clients]].

## In the editor

| Symptom | What it is | Fix |
|---|---|---|
| The editor will not accept input, or a drawing has lost its toolbar | Read mode is on. The same happens in the non-focused pane when one file is open in two panes | Toggle read and write mode from the pane's menu |
| A panel shows stale content after another surface changed the file | Another client wrote the file while it was open | Reopen the tab to pick up the current content |

## Search

Semantic search can fail with a generic search error while embeddings are being generated or throttled upstream. Retry after a minute. Filename search and `grep` are unaffected.

## Next steps

:::cards
- [[Limits]] — Sizes, counts, timeouts and rate limits in one table.
- [[Errors and Limits]] — Every error code, what causes it, and how to recover.
- [[Scopes]] — Every scope, what it unlocks, and the presets.
- [[Docs for Agents]] — llms.txt, /docs.md and the raw markdown render of every page.
:::