Troubleshooting
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
json
{ "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.
Terminal
npm cache clean --force
npx --min-release-age=0 -y @monofile/cli@latest --versionMCP 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
LimitsSizes, counts, timeouts and rate limits in one table.
Errors and LimitsEvery error code, what causes it, and how to recover.
ScopesEvery scope, what it unlocks, and the presets.
Docs for Agentsllms.txt, /docs.md and the raw markdown render of every page.