---
url: /build/errors-and-limits.md
description: >-
  The errors and limits you meet most often over MCP and the CLI, and what to do
  about each.
---

# Errors and limits

| Situation | What happens | What to do |
| --- | --- | --- |
| **Version conflict** | Someone changed the record since you read it. The write is refused. | Read it again and apply your change to the new version. Do not resend old content. |
| **Missing scope** | The tool is refused before anything changes. | Create a token with the scope you need. |
| **Token limited to other companies** In review | `NOT_FOUND` for a company outside the token, `TOKEN_COMPANY_LIMIT` for a tool that adds companies. | Use a token that covers the company. |
| **File too large** | A document over 4 MiB is refused. | Split or compress it. |
| **Roster file too large** | A team CSV over 500,000 bytes is refused. | Split the file. |
| **Repo export too large** | Export stops over 20,000 files, 8 MiB for one file, or 64 MiB in total. | Review the larger Repo in the app. |
| **Too many changes in one push** | A push is limited to 1,000 drafts and 1,000 documents. | Split it. |
| **Too many sign-in attempts** | Sign-in is limited to 40 requests in 15 minutes for one IP address. | Wait, then try again. |
| **No AI connection** | A tool that needs AI says so and saves nothing. | Turn on an AI key for the company in Settings. |
| **Stale onboarding file** | `onboarding import` refuses a file whose revision is old. | Export again, reapply your edits, import. |

## Ideas that hold everywhere

* **Preview is the default.** Pass `apply: true` over MCP or `--apply` in the CLI to save.
* **A draft is not a fact.** Saving through MCP or the CLI makes an advisor draft. Confirming happens in the app.
* **Sending is separate from saving.** Nothing here emails a client unless you ask for it by name.
