---
title: "Check codes"
description: "Every MAIN- code the specs define so far, grouped by area, with where you meet it, what it means and how to fix it."
section: "reference"
status: "Planned for 0.2"
spec: "errors"
canonical: "https://mainsdk.dev/docs/reference/check-codes"
updated: "2026-10-28"
---

# Check codes

> Every MAIN- code the specs define so far, grouped by area, with where you meet it, what it means and how to fix it.

Status: Planned for 0.2 · Canonical: https://mainsdk.dev/docs/reference/check-codes · Updated: 2026-10-28

Every finding from `mainsdk check` and every error the SDK raises carries a stable code: `MAIN-<AREA>-<NNNN>`. A code is assigned once and never reused or changed in meaning. Each one has a page at `https://mainsdk.dev/errors/<code>`, which is also the `type` of its [problem details](https://mainsdk.dev/docs/reference/errors).

Look any code up offline:

```text
$ npx mainsdk explain MAIN-DATA-0007
MAIN-DATA-0007  Record belongs to another user  (403)
cause  A query read a record owned by a different user.
fix    Scope the query with db.orders.for(user).
```

The **Raised by** column says where you meet the code: `check` (a gate finding before merge), `runtime` (an error or log from the SDK in your running app), or `CLI` (a command that refuses to run). A code not listed here is not defined yet. A family written `MAIN-<AREA>-*` is a group of Main 27 rules whose individual numbers arrive with the baseline pack.

## CHECK, CONFIG and CONTRACT

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-CHECK-0026` | check | An interface resolves to a local driver in production | Set a real driver in `main.env.prod.yaml` |
| `MAIN-CONFIG-0001` | check, runtime | Unsupported `schema` value in `main.yaml` | Use `schema: 1`; the error lists supported versions |
| `MAIN-CONFIG-0002` | check, runtime | `main.yaml` can't be read: bad indent, a tab, an anchor or tag, or a duplicate key; the error names the line | Fix the YAML at that line; main.yaml uses plain maps, lists and scalars |
| `MAIN-CONFIG-0003` | check, runtime | A value has the wrong format: money (`"$0.05"`), a rate (`$5/day`), a size (`25MB`) or a duration (`1h`) | Write the value in the format the error shows |
| `MAIN-CONFIG-0005` | check, runtime | No `main.yaml` in the project folder | Run `npx mainsdk init` |
| `MAIN-CONFIG-0004` | check, runtime | A literal value in a field marked secret | Use a `secret:` reference, for example `secret:RESEND_API_KEY` |
| `MAIN-CONFIG-0010` | check, runtime | A layer weakens its parent, for example adds a host `main.org.yaml` doesn't allow | Remove the change, or add an exception with rule, reason, owner and expiry |
| `MAIN-CONFIG-0020` | runtime | A config value fails its schema; the last good value is kept | Fix the value in your config store |
| `MAIN-CONFIG-0021` | runtime | A pushed `main.` value is looser than `main.yaml` allows, or a limit's period differs; the value is refused and the last good one kept | Push a value equal to or tighter than `main.yaml`, or change `main.yaml` in a reviewed deploy |
| `MAIN-CONFIG-0022` | runtime | A pushed key starts with `main.` but names a path that can't be pushed, such as `main.payments.driver`; the key is refused | Change that setting in `main.yaml` in a reviewed deploy |
| `MAIN-CONFIG-0023` | runtime | The config store can't be read (down, or a load timed out); the app serves its last good values, logged once per outage | Restore the store; the app needs no restart |
| `MAIN-CONTRACT-0003` | CLI | No driver version satisfies every interface range during `sync` | Widen a range or pick a driver that implements it; the error names both ranges |
| `MAIN-CONTRACT-0021` | CLI | A contract has no threat model (`mainsdk contract check`) | Add the interface's STRIDE threat model |
| `MAIN-CONTRACT-0030` | CLI | The vendored getqr.id `openapi.yaml` doesn't match the sha256 in its `vendor.yaml`, or the generated TypeSpec import is stale (ADR-0057) | Restore the vendored file and take a new version only through `contract diff --vendor getqr`; rebuild with `contracts:build` |
| `MAIN-CONTRACT-0031` | CLI | `contract diff --vendor getqr` found an upstream change that breaks an operation or field MainSDK uses; the finding names both | Keep the pin until the call is updated in the same pull request, or ask the GetQR ID team |
| `MAIN-CORE-0001` | runtime | Native core ABI version doesn't match the binding | Reinstall so the core and binding versions match; the error names both |
| `MAIN-CORE-0500` | runtime | Unknown error in a handler; no internal detail in production | Read the trace with `mainsdk explain <trace_id>` |
| `MAIN-PAGE-0001` | runtime | A list cursor is malformed, older than 24 hours, or made by a different query, tenant or user (400) | Start again without a cursor, or pass back the `next` value of the same query |
| `MAIN-PAGE-0002` | runtime | `limit` is not a whole number of at least 1 (400) | Pass a whole number from 1 up to the call's maximum |

## SECRET

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SECRET-0001` | check (build) | `mainsdk/secrets` imported from client code | Read the secret in server code only |
| `MAIN-SECRET-0002` | check | A key pattern in source code | Move the key to `secrets` and use `secret:NAME` |
| `MAIN-SECRET-0003` | check | A committed `.env` file other than `.env.example` | Remove it from git and use the secrets driver |
| `MAIN-SECRET-0004` | check (build output) | A value from a `secret:` reference is in a browser bundle | Keep the call on the server; the finding names the chunk |
| `MAIN-SECRET-0007` | runtime | Secrets provider unreachable; serving the last good value from memory | Restore the provider; nothing is written to disk |
| `MAIN-SECRET-0005` | runtime | A `secret:` reference names a secret that isn't set | Set it in your secrets manager, or in your shell for local development |

## FLAGS

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-FLAGS-0001` | runtime | A flag was evaluated with no definition in config; the fallback was served, logged once per name | Define `flags.<name>` in your config store, or pass the fallback you meant |
| `MAIN-FLAGS-0002` | runtime | A pushed flag definition is invalid; it was refused and the last good definition kept | Fix the definition: `enabled` as a boolean, `rollout` from 0 to 100 with at most two decimals, one of `user`, `in` or `notIn` per rule |
| `MAIN-FLAGS-0003` | runtime | A rule served a value of a different type from the fallback, or `enabled` got a non-boolean; the fallback was served, logged once per name | Serve a value of the same type as the fallback |

## AUTH and SESSION

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-AUTH-0001` | runtime | Not signed in (401 from `auth.require()`) | Sign in; the problem body carries a `fix` |
| `MAIN-AUTH-0006` | runtime | WhatsApp code reused, expired or tried too often; the challenge is closed | Start a new sign-in |
| `MAIN-AUTH-0007` | runtime | OIDC SSO callback with a mismatched `state` or `nonce` | Restart sign-in from your app |
| `MAIN-AUTH-0008` | runtime | SAML assertion unsigned, for the wrong audience, expired or replayed | Check the IdP metadata and clock for the organisation |
| `MAIN-AUTH-0040` | runtime | A sign-in challenge was verified a second time; a challenge works once | Start a new challenge with `auth.challenge.start` for each sign-in |
| `MAIN-AUTH-0041` | runtime | Invite used, expired, revoked, or accepted by a different email (410); a mismatch leaves the invite valid | Ask for a new invite, or sign in with the invited email |
| `MAIN-AUTH-0042` | runtime | Domain not verified, already verified by another tenant, or a public email domain | Publish the TXT record the fix shows, or use a domain you own |
| `MAIN-AUTH-0043` | runtime | The change would leave the tenant with no owner (409) | Make another member an owner first |
| `MAIN-AUTH-0044` | runtime | The tenant requires its SSO; this session came from another method (403) | Sign in through the organisation's SSO |
| `MAIN-AUTH-0045` | runtime | Invites, teams and domains are not available in a personal tenant (409) | Create an organisation with `auth.orgs.create` |
| `MAIN-AUTH-0046` | runtime | Sign-in link used, expired, unknown, or opened in a browser other than the one that asked (401; the challenge is closed) | Ask for a new link with `links.signIn()` from the same browser |
| `MAIN-AUTH-*`, `MAIN-SESSION-*` | check | Main 27 sign-in and session rules: home-made password storage, implicit flow, long-lived tokens, tokens in local storage | Use `auth` and its session cookies |

## TENANT

Planned for 0.3 (spec `tenancy`).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-TENANT-0001` | runtime | A tenant-scoped call ran with no tenant in context (500) | Run jobs and scripts inside `tenant.run(id, fn)`; requests get the tenant from the adapter |
| `MAIN-TENANT-0002` | runtime | The tenant doesn't exist, or the caller isn't a member or key holder (404, same body either way) | Switch to a tenant you belong to |
| `MAIN-TENANT-0003` | runtime | The tenant is suspended; tenant-scoped calls fail closed (403) | Resume the tenant, or list the call under `tenancy.suspended.allow` |
| `MAIN-TENANT-0004` | runtime | `tenant.system()` called from a file outside `tenancy.system.allow` | Move the admin code under a listed path |
| `MAIN-TENANT-0005` | runtime | A record, file, team or reference of another tenant was used; treated as not found (404) | Read it inside its own tenant |
| `MAIN-TENANT-0006` | runtime | The tenant's region store or database is not configured or not reachable; nothing is written elsewhere (503) | Configure the store for the tenant's region, or its entry in `tenancy.databases` |
| `MAIN-TENANT-0007` | runtime | Erasure refused: the tenant is active, under a legal hold, or still in its waiting period (409) | Suspend it first, lift the hold, or wait for `tenancy.erase.wait` |
| `MAIN-TENANT-0010` | check | A raw query on a tenant-scoped table has no `tenant_id` condition | Use `db.<model>` or add the `tenant_id` condition |
| `MAIN-TENANT-0011` | check | `tenant.system()` used in a file outside `tenancy.system.allow` | Move the code or list the path |
| `MAIN-TENANT-0012` | check, runtime | A per-tenant config or limit override loosens the app value | Only tighten per tenant |
| `MAIN-TENANT-0013` | check | Shared isolation on a driver with row-level security, but the migrations don't enable it | Regenerate the migrations with MainSDK |

## APIKEY

Planned for 0.3 (spec `apikeys`).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-APIKEY-0001` | runtime | No key, or a malformed one: wrong prefix, wrong length, bad checksum, or a key sent in the query string (401). Decided offline | Send the key as `Authorization: Bearer <key>` or in the `apikeys.header` header |
| `MAIN-APIKEY-0002` | runtime | Unknown, revoked or expired key (401). The body is the same for all three; the log says which | Create or rotate a key |
| `MAIN-APIKEY-0003` | runtime | The key's scopes don't include the permission this action needs (403) | Create a key with that scope, or call an action the key may use |
| `MAIN-APIKEY-0004` | runtime | Invalid `create` or `rotate` input: a scope not under `apikeys.scopes`, an expiry in the past or past `max-ttl`, an overlap over 30 days, or an empty name (400) | Fix the input the error names |
| `MAIN-APIKEY-0005` | runtime | The caller may not issue this key: no `apikeys.manage` permission, a scope the caller doesn't hold, or a tenant other than the current one (403) | Ask for the permission, or issue only scopes you hold in the current tenant |
| `MAIN-APIKEY-0006` | runtime | The key's rate limit is reached (429, with `Retry-After`) | Wait for `Retry-After`, or raise the rate with a new key |
| `MAIN-APIKEY-0007` | runtime | The key's environment doesn't match: a `test` key in `env: prod`, or a `live` key anywhere else (401). Decided offline | Use a key made for this environment |
| `MAIN-APIKEY-0008` | runtime | The key store can't be reached. Keys verified in the last 15 minutes are served from memory and this is logged once; other keys get 503 (retryable) | Restore the store; retry the call |
| `MAIN-APIKEY-0009` | runtime | `rotate` on a revoked or expired key (409) | Create a new key instead |
| `MAIN-APIKEY-0010` | check | A key in this app's format, with a valid checksum, is committed to source | Remove it, revoke the key and issue a new one |
| `MAIN-APIKEY-0011` | check | A scope under `apikeys.scopes` that no `access` permission defines | Define the permission in `access`, or remove the scope |

## PLAN

Planned for 0.3 (spec `entitlements`).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-PLAN-0001` | runtime | The tenant's plan doesn't include this feature (403, with an `upgrade` hint naming the plans that do) | Upgrade the plan, or grant the feature with `entitlements.grant` |
| `MAIN-PLAN-0002` | runtime | The tenant has reached this limit of its plan (403, with an `upgrade` hint) | Upgrade the plan, or raise the limit with `entitlements.grant` |
| `MAIN-PLAN-0003` | runtime | An override would remove a feature or lower a limit; overrides may only add (400) | Change the plan in `main.yaml` instead |
| `MAIN-PLAN-0004` | runtime | The plan store can't be reached; the last known plan is served, or the default plan for a tenant with none. Logged once per outage | Restore the store; nothing else to do |
| `MAIN-PLAN-0005` | runtime | A subscription event names a price under no plan, or carries no tenant; it is ignored and the plan is unchanged | Add the price to a plan under `plans.<name>.prices`, or tag the subscription with its tenant |
| `MAIN-PLAN-0006` | check, runtime | `plans` or `entitlements` is invalid: the default plan isn't defined, a name is both a feature and a limit, a limit has a bad value, a windowed usage source has a limit with no window, or a price is under two plans. The app doesn't start | Fix the key the error names |
| `MAIN-PLAN-0007` | runtime | A plan change for another tenant outside `tenant.system()`, or by a caller without the `entitlements.manage` permission (403) | Make the change inside `tenant.system()` in admin code, or grant the permission |
| `MAIN-PLAN-0008` | runtime | A feature or limit name that no plan declares. `has` returns false and logs once; `limit` and `within` throw (500) | Declare the name under `plans` |
| `MAIN-PLAN-0009` | runtime | The tenant has reached its plan's request rate (429, with `Retry-After`) | Wait for `Retry-After`, or move to a plan with a higher `requests` limit |
| `MAIN-PLAN-0010` | check | A feature or limit name used in code that no plan declares | Declare the name under `plans`, or fix the typo |

## ACCESS and POLICY

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-ACCESS-0001` | runtime | Access denied (403) | Check the role or relation the action needs |
| `MAIN-ACCESS-0004` | check | Relations need a ReBAC driver (openfga, spicedb, permit) or Cedar entities | Switch `access.driver` or model the relation in Cedar |
| `MAIN-ACCESS-0007` | runtime | Remote engine unreachable and no cached decision; denied (fail closed) | Restore the engine; tune `access.unreachable.cache` |
| `MAIN-ACCESS-0011` | check | OpenFGA 1.8.0 to 1.13.1 pinned (CVE-2026-34972, wrongly permissive BatchCheck) | Upgrade OpenFGA past 1.13.1 |
| `MAIN-ACCESS-0020` | runtime | An attribute source timed out or is down, so `access` denied the request | Wait for the source or fix its driver; never turn the gate off |
| `MAIN-POLICY-0004` | runtime (load) | A repo policy weakens an org policy; loading fails, naming both files | Remove the repo policy or change it at the org layer |
| `MAIN-POLICY-0009` | runtime | A new policy set failed to load; the previous version stays in force | Fix the syntax; run `mainsdk test policy` |
| `MAIN-POLICY-0011` | runtime (load) | A Cedar policy uses a construct the built-in TypeScript engine doesn't support yet; it names the construct and line and never ignores it | Rewrite the policy without the construct, or use the OPA driver |

## DATA, KEYS and PRIV

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-DATA-0001` | check | Raw database client used outside MainSDK | Wrap it: `withPrisma(client)` or `withDrizzle(db)` |
| `MAIN-DATA-0007` | runtime | Record belongs to another user (403) | Scope the query with `db.<model>.for(user)` |
| `MAIN-DATA-0013` | check | A query joins tables across regions | Query each region separately; combine only totals |
| `MAIN-DATA-0020` | check | A field labelled `pan`: card numbers are never stored | Use hosted checkout through `pay`; drop the field |
| `MAIN-DATA-0021` | check | A field that holds personal data has no label | Add a label: `personal`, `sensitive`, `child` or `phi` |
| `MAIN-DATA-0030` | check | SQLite local driver in production | Set `db.driver` to `postgres`, `neon` or `supabase` for prod |
| `MAIN-DATA-0008` | runtime | The record isn't there, with tenancy off (404) | Check the id and the model |
| `MAIN-DATA-0009` | runtime | A create repeats an id or a declared unique value (409) | Leave `id` out, or change the unique value |
| `MAIN-DATA-0031` | runtime | The local SQLite driver can't start: this Node has no `node:sqlite` (500) | Use Node 22.18 or later, or the postgres driver |
| `MAIN-DATA-0032` | runtime | `db.driver` is not built, or a Postgres driver has no client (400) | Use sqlite, postgres, neon or supabase, and pass the `postgres` option |
| `MAIN-DATA-0050` | runtime | A query ran past its statement timeout and was cancelled (503, not retried) | Add an index or narrow the query; raise `db.timeout.request` up to 30s, or use a job |
| `MAIN-DATA-0052` | runtime | No connection was free within `db.pool.acquire` (503 with `Retry-After: 1`) | Retry; raise `db.pool.max` or shorten transactions |
| `MAIN-DATA-0053` | runtime | A query took longer than `db.slow` (warn log, once a minute per query shape) | Add an index or narrow the query |
| `MAIN-DATA-0054` | runtime | One query shape ran more than `db.repeat` times in one request or job (warn log) | Load them with one `where: { id: { in: ids } }` query |
| `MAIN-DATA-0060` | runtime | `ifVersion` doesn't match the record's version (409; 412 from `If-Match`) | Read the record again and retry |
| `MAIN-DATA-0063` | runtime | `restore` of a record not in trash, or past its trash period (404) | Restore within the trash period |
| `MAIN-DATA-0066` | runtime | A write to a versioned record came with no `If-Match` (428) | Send the ETag you read, or `If-Match: *` |
| `MAIN-DATA-*`, `MAIN-API-*` | check | Main 27 database and API rules: SQL built from strings, shared admin credentials, unvalidated input, open CORS | Use typed queries through `db`; follow the fix in each finding |
| `MAIN-KV-0001` | runtime | `incr` was given a step that is not a whole number (400), or the key holds a value that is not a whole number (409) | Pass an integer `by`; use `incr` only on keys it created |
| `MAIN-KV-0002` | runtime | `ttl` is not a positive duration (400) | Pass milliseconds or a duration such as `30s` |
| `MAIN-KV-0003` | runtime | A key is empty or longer than 512 characters (400) | Use a shorter, non-empty key |
| `MAIN-KEYS-0001` | check | Local keys driver in production | Set `keys.driver` to a KMS driver for prod |
| `MAIN-KEYS-0004` | runtime | Data can't be decrypted because its owner's key was destroyed (erasure) | Expected after `privacy.erase` with `keys.per-user: true` |

## NET

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-NET-0001` | check | Raw socket, another HTTP client or direct `fetch` outside the SDK: `new WebSocket`, `EventSource`, `node:http`, `node:https`, `node:dgram`, `ws`, or `git`, `curl` or `wget` run as a child process | Call through `http.*` or a driver; for a program, declare it under `permissions.processes` and run it with `system.run` |
| `MAIN-NET-0002` | check, runtime | Call to a host not in `network.allow` (or not declared by a driver) | Add the host to `network.allow`, or remove the call |
| `MAIN-NET-0003` | runtime | Redirect to an undeclared host refused | Declare the target host or call it directly |
| `MAIN-NET-0004` | check | A third-party API offers less than TLS 1.2 (TLS 1.3 is the minimum for endpoints your app serves, under `MAIN-NET-*`) | Ask the provider to upgrade; meanwhile an exception with an expiry |
| `MAIN-NET-0005` | runtime | An entry in `network.allow` is not an IP, a CIDR range, an exact host or a `*.domain` (for example a prefix length out of range) | Fix the entry; the error names it |
| `MAIN-NET-0006` | runtime | A request was redirected more times than the SDK follows, or `redirect: "error"` met a redirect | Call the final URL directly, or fix the redirect loop |
| `MAIN-NET-0007` | check | The code connects to a host that `network.allow` doesn't list; the finding names the call (`http`, `websocket`, `event-stream`, `database`, `git`) | Add the host to `network.allow`, or remove the call; `npx mainsdk discover` prints the lines to add |
| `MAIN-NET-0008` | runtime | `http.json` or `http.events` got a non-2xx answer (429 when the provider rate-limits, else 502), or JSON that didn't parse; the body is never echoed | Check the URL, the credentials and the service status, or read the response with `http.fetch` |
| `MAIN-NET-0009` | runtime | An outbound call timed out: the connect or total timeout of its last attempt, or its deadline, passed (504; the error names which) | Raise the timeout for that host or call, or check the provider's latency |
| `MAIN-NET-0010` | runtime | The circuit breaker for the host is open, or half-open with its probe in flight; no request was sent (503, `retryable`, `retryAfter` is the rest of the cooldown) | Wait for `retryAfter`, and check the provider's status; breakers are per app instance |
| `MAIN-NET-0011` | runtime | An outbound call failed with a network error (refused, reset, DNS failure) on its last attempt (502; states the number of attempts) | Check the host, DNS and the provider's status |
| `MAIN-NET-0012` | runtime | A value under `network.http` is invalid: a bad duration, `attempts` outside 1 to 10, `failures` outside 1 to 100 %, `min` below 1, or an unknown key (fails at load; names the key) | Fix the value the error names |
| `MAIN-NET-*` | check | Main 27 network rules: plain HTTP, TLS below 1.3 on public endpoints | Serve over TLS 1.3 |

## PERM

Permission codes cover the server's own disk, operating system facts and programs (spec `app-permissions`). They appear only for what `permissions` in main.yaml declares; see [Declare what your app uses](https://mainsdk.dev/docs/guides/declare-what-your-app-uses).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-PERM-0001` | check | Raw `node:fs`, `node:os` or `node:child_process` used outside a driver | Use `disk` for files and `system` for facts and programs |
| `MAIN-PERM-0002` | runtime | In `enforce` mode, a `disk` path, a `system` fact or a program is used but not declared under `permissions` (403) | Declare it under `permissions` in main.yaml, or remove the code that asks |
| `MAIN-PERM-0003` | check | A `disk` path, a `system` fact or a program found in the code isn't declared under `permissions` | Declare it; `npx mainsdk discover` prints the lines to add |
| `MAIN-PERM-0004` | runtime | An unknown name under `permissions.system` | Use one of `user`, `hostname`, `platform` or `network-interfaces` |
| `MAIN-PERM-0005` | runtime | A declared program could not start, for example because it is not installed on the server | Install it on the server, or check its name |

## AI, MCP and actions

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-AI-0001` | check | The driver's training setting is weaker than `ai.data.training` | Pick a driver or plan that meets it |
| `MAIN-AI-0005` | runtime | Prompt injection suspected in a tool result; wrapped as untrusted data | Review the source of the tool result |
| `MAIN-AI-0007` | runtime | Call refused: it would pass a spend limit | Raise `ai.limits` or wait for the period to reset |
| `MAIN-AI-0010` | runtime (start) | `ai.tool()` for a function not declared with `action()` | Declare it with `action()` |
| `MAIN-AI-0011` | runtime | Typed output does not match `schema` after its repairs (one by default, up to two with `repairs`); no value is returned | Fix the schema or the prompt; never use the raw reply as if it were valid |
| `MAIN-AI-0002` | runtime | The model isn't in the `ai.models` allowlist (403) | Add it to `ai.models`, or call an allowed model |
| `MAIN-AI-0003` | runtime | The model provider answered with an error (502); the message has the status, never the body | Check the key, the model name and the provider's status, then retry |
| `MAIN-AI-0004` | runtime | No price is set for the model, so its spend can't be limited | Add the model to `ai.prices` |
| `MAIN-AI-0006` | runtime | The driver has no embeddings, for example `anthropic` | Use a driver with embeddings, such as `openai` |
| `MAIN-AI-0008` | runtime | An agent's model call waits for a person's approval; nothing reached the provider (202) | A person approves it, then the call runs |
| `MAIN-AI-0012` | runtime | A call passed neither or both of `prompt` and `messages` (400) | Pass `prompt` for one instruction, or `messages` for a conversation |
| `MAIN-AI-0013` | runtime | `ai.driver` names a driver that isn't built yet | Use `fake`, `anthropic` or `openai` until it ships |
| `MAIN-AI-0014` | runtime | A model verb option is invalid: `repairs` is not 0, 1 or 2, a label list is empty or repeats a label, or a summary `length` is unknown (400); no request is sent | Pass a valid option, as the verb's page lists them |
| `MAIN-AI-0015` | runtime | A speech or transcription option is invalid: both or neither of `text` and `input`, an unknown format or sample rate, or empty text (400); nothing is sent | Pass one of `text` or `input` and a listed format |
| `MAIN-AI-0016` | runtime | Voice clone refused: no granted `voice-clone` consent recorded by the owner in their own session (403) | The voice's owner records the consent themselves, then clones |
| `MAIN-AI-0017` | runtime | The consent statement's transcript doesn't match `ai.speech.clone.script`, or the statement and samples aren't one speaker (422) | The owner reads the script aloud again |
| `MAIN-AI-0018` | runtime | The voice can't be used: blocked or deleted after consent was revoked or the owner erased, or the caller isn't its owner or in its shared tenant (403) | Use another voice; only the owner can clone it again |
| `MAIN-AI-0019` | check, runtime | A voice that isn't an alias under `ai.speech.voices` or a cloned voice id | Add an alias under `ai.speech.voices`, or use a cloned voice id |
| `MAIN-AI-0020` | runtime | Speech text holds labelled data and the speech driver's data use doesn't meet `ai.data` (403); nothing is sent | Use a driver declared with zero retention, or leave the data out |
| `MAIN-AI-0021` | runtime | The driver doesn't offer this: speech, transcription, streaming, diarisation or cloning (501) | Pick a driver that offers it, as its page lists |
| `MAIN-AI-0022` | runtime | Deleting a cloned voice at the provider failed; the voice stays blocked and the delete is retried (logged) | Nothing to do; check the provider's status if it keeps failing |
| `MAIN-AI-0023` | runtime | Audio is larger than `ai.speech.max-audio`, or a live transcription passed `max-duration` (413) | Send shorter audio, or raise the limit on purpose |
| `MAIN-MCP-0001` | runtime | The server is not in `mcp.servers`; no request leaves the process | Add the server to `main.yaml` on purpose, and allow its host under `network` |
| `MAIN-MCP-0002` | runtime | A pinned server's tool description changed | Read the diff in `mainsdk check`; a person accepts the new description |
| `MAIN-MCP-0003` | runtime | A tool description changed after signing; the tool is left out | Re-sign by releasing again; investigate the change |
| `MAIN-MCP-0004` | runtime | A call limit was reached, for example `per-user: 100/day`; the call is refused before any request | Wait for the period to reset, or raise `limits` on purpose |
| `MAIN-MCP-0005` | runtime | A write or destructive tool call wasn't confirmed by the person, so nothing ran (returned in the tool result) | Wire `elicit` so the person can accept, or have them accept |
| `MAIN-MCP-0006` | runtime | The MCP server answered with an error or not at all (502) | Check the server and the tool arguments |
| `MAIN-MCP-0007` | runtime | A remote server's protected resource metadata is missing or invalid, or its `resource` isn't the server's URL (502) | Fix the server's protected resource metadata, or ask its owner to |
| `MAIN-MCP-0008` | runtime | The remote server's authorization server offers no dynamic registration and no `client-id` is set for it (500) | Set `client-id` for the server under `mcp.servers` |
| `MAIN-MCP-0009` | runtime | A token sent to the app's MCP server was issued for another resource (401); it is never passed on | Send a token issued for this app's MCP server |
| `MAIN-MCP-0010` | runtime | A token sent to the app's MCP server lacks the scope the tool needs (403, `insufficient_scope`) | Ask the person to connect again with the scope the tool needs |
| `MAIN-ACTION-0001` | runtime | An action's input failed its schema (400) | Send input that matches the action's schema |

## SCHEMA and parse

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SCHEMA-0001` | runtime | A value does not match its schema (422); the problem's `errors` lists each issue's path, code and message, never the value | Send a value that matches the schema; read each `errors` entry |
| `MAIN-SCHEMA-0002` | runtime | The input is longer than the parser's size limit (413); nothing was matched | Send a shorter input, or raise `maxLength` on purpose |
| `MAIN-SCHEMA-0003` | runtime (definition) | A pattern has a nested quantifier, such as `(a+)+`, and is refused when the schema or parser is defined (500) | Rewrite the pattern so no repeated group sits inside another repeat |
| `MAIN-SCHEMA-0004` | runtime | A parser found no match, or no parser in `parse.first` matched (422); the input is not echoed | Check the input's format, or add a parser or a model fallback to `parse.first` |

## AGENT

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-AGENT-0001` | runtime | A call names an agent that is not under `agents` | Fix the name, or add the agent under `agents` |
| `MAIN-AGENT-0002` | runtime | The agent is over its budget; the call is refused and nothing reaches the provider | Wait for the budget period to reset, or raise the budget on purpose |
| `MAIN-AGENT-0003` | runtime | An agent tried to approve its own step | A person approves; an agent never can |
| `MAIN-AGENT-0004` | runtime | The agent is switched off (`enabled: false`) | Set `enabled: true` when a person decides to |
| `MAIN-AGENT-0005` | runtime | An approval id that isn't pending: unknown, already approved or expired | List pending approvals and use one of their ids |
| `MAIN-AGENT-0006` | runtime | The store that counts budgets did not answer, and the agent has a budget, so the call is refused (503, retryable) | Check `runtime.store`; calls with no budget keep running |
| `MAIN-AGENT-0007` | runtime | A sync budget call (`admit`, `charge`, `request`) on a store other instances share | Use `reserve`, `settle`, `release` or `ask` |

## Messaging, payments, files, webhooks and events

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-EMAIL-0001` | check | Marketing email without an unsubscribe link (the rule behind the `email.unsubscribe` guarantee) | Send marketing with `email.marketing({ …, unsubscribe })` |
| `MAIN-NOTIFY-0003` | runtime | SMS skipped: no recorded opt-in | Record SMS consent first |
| `MAIN-NOTIFY-0004` | runtime | WhatsApp skipped: no consent | Record WhatsApp consent first |
| `MAIN-PAY-0001` | check | A form posts card data to an app route | Use hosted checkout: `pay.checkout()` |
| `MAIN-PAY-0030` | runtime | `pay.agent` named a payee not in `pay.payees`, or an amount above the payee's `max` | Declare the payee with its `host` and `max`, and allow the host under `network` |
| `MAIN-PAY-0002` | runtime | An amount isn't positive money, or doesn't fit the currency's minor units (400) | Pass money such as `"$20.00"`, or a positive integer in minor units |
| `MAIN-PAY-0010` | runtime | A payment webhook failed verification: bad or missing signature, or outside the 5-minute window (400); no handler ran | Check the webhook secret, and pass the raw, unparsed body |
| `MAIN-PAY-0020` | runtime | The payment provider answered with an error | Look up the request in the provider's dashboard logs |
| `MAIN-PAY-0031` | runtime | `pay.agent` was called with no agent payment rail set | Pass `agentRail` when you create the app; MainSDK holds no keys or funds |
| `MAIN-PAY-0032` | runtime | A held agent payment was sent before a person approved it | A person approves it first |
| `MAIN-FILES-0002` | runtime | `access` denied this user a file URL (403), or someone other than the uploader called `files.complete()` | Read or complete as the owner, or add an access rule for the reader |
| `MAIN-FILES-0005` | runtime | `files.complete()` ran the scan and found an infected file; the upload fails and the file is quarantined, with no readable URL | Nothing to fix in code; ask the user for a clean file |
| `MAIN-FILES-0010` | check | A storage SDK used for user uploads outside a `files` driver, for example `@vercel/blob` in route code | Upload through `files`, and pick the store with `files.driver` |
| `MAIN-FILES-0003` | runtime | A per-call `maxSize` is above `files.maxSize` | Lower it in the call, or raise `files.maxSize` on purpose |
| `MAIN-FILES-0004` | runtime | An upload target is invalid, already used or older than 15 minutes (403) | Ask the server for a new one with `files.uploadUrl()` |
| `MAIN-FILES-0006` | runtime | The file is larger than the upload allows (413); it is removed and never readable | Send a smaller file |
| `MAIN-FILES-0007` | runtime | The file's type isn't one the upload allows (415); it is removed and never readable | Send one of the allowed types |
| `MAIN-FILES-0008` | runtime | `files.complete()` ran before any bytes reached the store (409) | Send the file to `upload.url` first |
| `MAIN-FILES-0011` | runtime | The s3 driver found no credentials: no keys in `main.yaml` and no runtime role | Set `files.accessKeyId` and `files.key: secret:NAME`, or run with an IAM role |
| `MAIN-FILES-0012` | runtime | `files.upload()` from the server isn't supported by the s3 driver yet | Use `files.uploadUrl()` and let the browser send the file |
| `MAIN-FILES-0013` | runtime | The store answered with an error (502) | Check the bucket, region and credentials; the message has the store's status |
| `MAIN-FILES-0014` | runtime | `files.driver` names a driver that isn't built yet | Use `local`, `memory` or `s3` until it ships |
| `MAIN-FILES-0015` | runtime | The getqr.id API has no endpoint for this step, such as downloading or deleting stored bytes (501) | Send files with `files.uploadUrl()` and read them with `files.url()`; getqr.id scans on its side |
| `MAIN-SHARE-0001` | check | A link shortener, deep-link or QR code library imported in app code, such as `bitly`, `tinyurl`, `qrcode`, `qrcode.react`, `react-qr-code`, `qr-code-styling`, `branch-sdk` or `@react-native-firebase/dynamic-links` | Share through `share()` or `links` and getqr.id (ADR-0009, ADR-0056) |
| `MAIN-SHARE-0002` | runtime | `expiresIn` is longer than `share.max-expiry` (400) | Use a shorter `expiresIn`, or raise `max-expiry` on purpose |
| `MAIN-SHARE-0003` | runtime | A share asked for access other than `read` (400); share links never grant writes | Use `access: "read"` |
| `MAIN-SHARE-0004` | runtime | `share.stats()` was called without the person's consent (403) | Ask for analytics consent, then pass `consent: true` |
| `MAIN-SHARE-0005` | runtime | getqr.id answered a share or stats call with an error | Check the key, its scopes and the plan; quote the request id to support |
| `MAIN-SHARE-0006` | runtime | getqr.id returned a share that breaks the rules (kept forever, no expiry, or off getqr.id); it is revoked and the call fails (502) | Check the plan and the key |
| `MAIN-SHARE-0007` | check | Code calls, or `network.allow` lists, a link shortener, deep-link or QR rendering service such as `api-ssl.bitly.com`, `tinyurl.com`, `is.gd`, `api.short.io`, `firebasedynamiclinks.googleapis.com`, `api2.branch.io` or `api.qrserver.com` | Remove the call and the `network.allow` entry; share through `share()` (ADR-0056) |
| `MAIN-SHARE-0008` | runtime | `share.driver: local` in production; the app refuses to start (500) | Set `share.driver: getqr` and `share.key` in `main.env.prod.yaml` |
| `MAIN-SHARE-0009` | runtime | A local share link was opened after it expired or was revoked (410) | Make a new share |
| `MAIN-SHARE-0010` | runtime | `share.update` was asked to keep a share forever (400); share links always expire, and placements are the only kept links | Use `extend` within `max-expiry`, or a placement for a printed QR code |
| `MAIN-SHARE-0011` | runtime | `share.placements.create` failed its row checks and created nothing (422; the problem lists each row, field and reason) | Fix the listed rows and send all of them again with the same idempotency key |
| `MAIN-SHARE-0012` | runtime | A getqr.id webhook event type that isn't in the pinned contract; acknowledged, logged once per type, not passed on | Take the new getqr.id contract version with `contract diff --vendor getqr` |
| `MAIN-SHARE-0013` | runtime | A share's `title` or `metadata` holds personal data, `metadata` has more than 16 keys or a reserved `mainsdk_` key, or a `contact` share isn't the signed-in person's own (400) | Use record ids your app resolves after sign-in; share only the person's own contact card |
| `MAIN-LINK-0001` | runtime | Invite link used up, expired, revoked, or accepted by a session whose verified email isn't the bound one (410; a mismatch leaves the invite valid) | Ask the inviter for a new invite, or sign in with the invited email |
| `MAIN-LINK-0002` | runtime | `links.create` or `links.invite` named a screen not in `links.routes`, or params missing or not declared (400) | Declare the screen and its params under `links.routes` |
| `MAIN-LINK-0003` | check | A route in `links.routes` declares a param that identifies a person: `email`, `phone`, `name`, `ip`, `token` or a labelled field | Pass a record id and resolve it after sign-in |
| `MAIN-LINK-0004` | check | `links.apps` is missing what association files need (iOS `team-id` and `bundle-id`, Android `package` and a `sha256`), or `links.base` isn't an HTTPS origin | Add the missing identifiers; the finding names them |
| `MAIN-LINK-0005` | check, runtime | `links.signIn` is called but `link` isn't in `auth.methods` (runtime: 400) | Add `link` to `auth.methods`, or remove the call |
| `MAIN-HOOK-0002` | runtime | Incoming webhook with a wrong signature or a timestamp too old (400) | Check the signing secret and the sender's clock |
| `MAIN-HOOK-0003` | check, runtime | `webhooks.receive` names neither a key under `webhooks.inbound` nor a preset, or an entry names an unknown preset | Declare the endpoint under `webhooks.inbound` with a listed preset |
| `MAIN-HOOK-0004` | runtime | A customer endpoint URL is refused: not `https`, carries credentials, or is or resolves to a loopback, private, link-local, shared, multicast or metadata address (400; a delivery fails without connecting) | Use a public `https` URL with no credentials |
| `MAIN-HOOK-0005` | runtime | The tenant already has `webhooks.endpoints.max-per-tenant` endpoints (409) | Delete an endpoint, or raise the limit on purpose |
| `MAIN-HOOK-0006` | runtime | An event type that isn't under `webhooks.endpoints.events` (400) | Subscribe to a listed type, or add it to `main.yaml` |
| `MAIN-HOOK-0007` | runtime | An endpoint was disabled after `disable-after` failures; an audit event and `webhook.endpoint.disabled` are written | Fix the receiver, then enable the endpoint again |
| `MAIN-HOOK-0008` | runtime | A test or redeliver to a disabled endpoint (409) | Enable the endpoint first |
| `MAIN-HOOK-0009` | runtime | No endpoint or delivery with that id in the current tenant (404) | Use an id from `webhooks.endpoints.list` |
| `MAIN-HOOK-0010` | runtime | An endpoints call without the `webhooks.manage` permission (403) | Grant `webhooks.manage` to the person who manages endpoints |
| `MAIN-HOOK-0011` | check | A `twilio` inbound entry has no `public-url` | Set `public-url` to the URL Twilio calls |
| `MAIN-HOOK-0012` | CLI | `mainsdk webhooks replay` refused: not a dev environment, no `mainsdk dev` running, or an unknown id (exit 2) | Run `mainsdk dev`, then pick an id from `mainsdk webhooks list` |
| `MAIN-EVENT-0004` | check | A breaking event schema change under the same version | Publish the change as a new event version |
| `MAIN-EVENT-0010` | check, runtime | A broadcast payload is larger than `max-payload` (runtime), or `max-payload` is over 1MB (check) | Send less data, or lower `max-payload` to 1MB or less; use `events.publish` or `jobs` for large messages |
| `MAIN-EVENT-0011` | check, runtime | `events.broadcast` uses the `local` driver in production, so other instances never receive it | Set `events.broadcast.driver: redis` in `main.env.prod.yaml` |
| `MAIN-EVENT-0012` | runtime | A broadcast topic doesn't match `^[a-z0-9][a-z0-9._-]{0,127}$`, or the payload isn't JSON | Use a lowercase topic such as `cache.invalidate`, and send JSON |
| `MAIN-EVENT-0013` | runtime | A broadcast was dropped because the driver is unreachable; the call resolves with `dropped: true` and logs once per outage | Restore the driver. Broadcast is best effort, so anything that must happen goes through `events.publish` or `jobs` |

## LOG, TUF and the Main mark

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-LOG-0003` | runtime | `MAINSDK_DEBUG=driver` ignored in production | Use a debug session (phase 2) |
| `MAIN-LOG-0005` | runtime | An attribute not in `telemetry@1` was dropped before export | Remove the attribute or propose it for the contract |
| `MAIN-LOG-0010` | runtime | Audit sink unavailable; buffering to local disk | Restore the sink |
| `MAIN-OBS-0001` | runtime | An observer threw or rejected; caught, the request is untouched, and the observer keeps receiving | Fix the observer; it is logged at most once a minute |
| `MAIN-OBS-0002` | runtime | An observer's queue was full and its oldest events were dropped | Make the observer faster, or raise its `max` |
| `MAIN-OBS-0003` | runtime | An observer's synchronous work took over 10 ms and blocked the event loop | Move the work into an async step or a job |
| `MAIN-OBS-0004` | runtime (testing kit) | A published payload breaks its channel schema | Match the payload to the channel's schema, or add a new channel version |
| `MAIN-OBS-0005` | runtime | `observe()` named a channel that isn't in the registry, or a pattern that matches none | Use the channel the message suggests; see `observe.channels()` |
| `MAIN-TUF-0001` | runtime | Rollback: the mirror served older metadata; the newer version is kept | None in your app; report the mirror |
| `MAIN-TUF-0004` | runtime | Delivered packs are stale; the last good pack stays in force | None needed; it refreshes when the mirror is back |
| `MAIN-INFO-0002` | CLI | The signed `/.well-known/mainsdk.json` doesn't verify (exit 1) | Treat the record as untrusted |
| `MAIN-CRYPTO-0002` | check | A Main 27 crypto rule, in the family that refuses MD5, SHA-1 and DES | Use `crypto` or `keys` |
| `MAIN-LOG-*`, `MAIN-CRYPTO-*` | check | Main 27 logging and crypto rules: secrets or personal data in logs, MD5, SHA-1, DES | Follow the fix in each finding |
| `MAIN-SUPPLY-*`, `MAIN-RELEASE-*` | check | Main 27 supply-chain rules: unpinned or unverified packages, unsigned builds | Follow the fix in each finding |

## ANALYTICS

Planned for 0.3 (spec `analytics`).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-ANALYTICS-0001` | runtime | A product event that `analytics.events` doesn't declare (throws in dev and test; dropped and logged once per name in production) | Declare the event under `analytics.events` |
| `MAIN-ANALYTICS-0002` | runtime | An event's props fail its schema (throws 422 with issue paths in dev and test; dropped and logged once per name in production) | Send props that match the declared types |
| `MAIN-ANALYTICS-0003` | runtime | An event was dropped: no consent for its purpose. Logged as a count, never with the person | Collect consent for the event's purpose |
| `MAIN-ANALYTICS-0004` | runtime | A query names an undeclared event, prop or metric, or a `by` the query kind doesn't take (400) | Declare the name, or use a `by` the query kind takes |
| `MAIN-ANALYTICS-0005` | runtime | A metric attribute that isn't declared was dropped, or a metric passed 1,000 attribute combinations and the rest were folded into `_other` | Declare the attribute, or use fewer distinct values |
| `MAIN-ANALYTICS-0006` | runtime | A driver in `analytics.to` is unreachable; events were buffered, then dropped with a counter | Restore the driver; nothing else to do |
| `MAIN-ANALYTICS-0007` | runtime | `analytics.query` called without `builtin` in `analytics.to` (501) | Add `builtin` to `analytics.to` |
| `MAIN-ANALYTICS-0008` | runtime | The event's region store isn't configured or reachable; the event was dropped and written nowhere else | Configure the store for the tenant's region |
| `MAIN-ANALYTICS-0010` | check | `analytics.track` or `page` with an event name that isn't declared, or isn't a string literal | Declare the event and pass its name as a string literal |
| `MAIN-ANALYTICS-0011` | check | A prop or metric attribute that would identify a person: a name such as `email`, `phone`, `name`, `ip`, `userId`, `deviceId`, `idfa`, `gaid` or `fingerprint`, or a field with a data label | Remove the identifying prop; use a declared, non-identifying one |
| `MAIN-ANALYTICS-0012` | check | A driver in `analytics.to` doesn't serve a region the app stores data in, or declares cross-app identifiers or third-party cookies | Pick a driver that serves your regions without cross-app identifiers |
| `MAIN-ANALYTICS-0013` | check | A children's audience (`users.audience: children`) with a per-person driver (`posthog`) in `analytics.to` | Use `builtin` or `otel` for a children's audience |

## HEALTH

Spec `health`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-HEALTH-0001` | runtime | This instance is not ready: starting, draining, or a critical dependency is down (503 on `/readyz`) | Wait for start-up, or restore the dependency |
| `MAIN-HEALTH-0002` | runtime | A request arrived after the app stopped accepting work (503 with `Retry-After` and `Connection: close`) | Retry; the load balancer should stop sending traffic once `/readyz` fails |
| `MAIN-HEALTH-0003` | runtime | The shutdown deadline cut work that was still running; the record lists what was released | Raise `health.deadline`, or shorten the work |
| `MAIN-HEALTH-0004` | runtime | A probe threw or timed out; its dependency is marked down (logged once per change) | Fix the dependency or the probe |
| `MAIN-HEALTH-0005` | check | An `slo` value is invalid: availability outside 90% to 99.999%, or a latency that isn't a duration | Use a percentage in range and a duration such as `300ms` |
| `MAIN-HEALTH-0006` | check | `health.critical` names a dependency the app doesn't configure, or names `mainsdk-cloud` or `tuf`; or `drain-delay` plus 2s is not less than `deadline` | List only dependencies the app configures; raise `deadline` or lower `drain-delay` |
| `MAIN-HEALTH-0010` | runtime | The availability error budget is burning faster than a burn rule allows | Find the failing dependency or release |
| `MAIN-HEALTH-0011` | runtime | The latency budget is burning faster than a burn rule allows | Find the slow call or release |

## ALERT

Spec `alerts`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-ALERT-0001` | check | An `alerts` value is invalid: an unknown driver, source or severity, a route to an undeclared recipient, a quiet-hours time or time zone that doesn't parse, or an escalation `after` shorter than `group.wait` | Declare every recipient a route names, use a known driver and an IANA time zone, and escalate after the group wait |
| `MAIN-ALERT-0002` | check | Production has an `alerts` section, but no route sends `critical` alerts to a recipient | Add a route for `severity: critical`, or a default route with no `match` |
| `MAIN-ALERT-0003` | check | A `webhook` recipient's host isn't in `network.allow`, or a recipient key or webhook URL is written as a literal | Add the host to `network.allow` and reference keys and URLs as `secret:NAME` |
| `MAIN-ALERT-0010` | runtime | An alert was raised or resolved; the log record carries the alert | Nothing to fix; follow the alert's runbook |
| `MAIN-ALERT-0011` | runtime | A recipient failed after its last retry; the others were still sent to | Check the recipient's key or URL with `mainsdk alerts test <recipient>` |
| `MAIN-ALERT-0012` | runtime | The runtime store didn't answer; dedupe and escalation fell back to this instance | Restore the store; until then each instance may send once |
| `MAIN-ALERT-0013` | runtime | `alerts.raise` refused or trimmed an input: a key over 200 characters, more than 20 attrs, or an attr outside `telemetry@1` | Shorten the key and send only `telemetry@1` attributes |
| `MAIN-ALERT-0014` | runtime | `alerts.ack` refused: the caller lacks `alerts.manage` (403) | Grant `alerts.manage` to the people who acknowledge alerts |
| `MAIN-ALERT-0015` | runtime | A recipient passed `max-per-hour`; the rest of the hour arrives as one summary | Group more alerts, fix the noisy source, or raise `max-per-hour` |

## RESOURCE

Spec `resources`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-RESOURCE-0001` | runtime | A new non-critical request or realtime connection was shed (503 with `Retry-After`); logged at most once a minute with a count | Retry after the delay; add capacity, or list the route under `resources.critical` if it must never be shed |
| `MAIN-RESOURCE-0002` | runtime | The instance entered or left `pressure` or `shed`, with the reasons and the values | Find what uses the CPU, event loop or memory; `mainsdk status` shows the snapshot |
| `MAIN-RESOURCE-0003` | check | A `resources` value is invalid: a percentage outside 10% to 100%, a `loop` under 20ms, a `shed` threshold not above its `pressure` threshold, a `critical` pattern that doesn't parse, or `nice` outside 0 to 19 | Use values in range and a `shed` threshold above `pressure` |
| `MAIN-RESOURCE-0004` | runtime | `nice` couldn't be applied; the app starts anyway (logged once) | Remove `nice`, or run where the process may lower its own priority |
| `MAIN-RESOURCE-0005` | runtime | Background work waited longer than `max-pause`; it now runs one at a time until pressure ends | Add capacity, or move the background work to a worker process |
| `MAIN-RESOURCE-0006` | runtime | The V8 heap limit is above the container's memory limit, so the process can be killed before the heap fills | Set `--max-old-space-size` to the value the record names |

## SEAL

Spec `seal`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SEAL-0001` | runtime | The files on disk don't match the sealed build hash (logged in warn mode; the app refuses to start in refuse mode) | Redeploy the sealed build |
| `MAIN-SEAL-0002` | runtime | No seal, or an unreadable one, in an environment other than dev while `seal.mode` isn't `off` | Run the seal step in the build |
| `MAIN-SEAL-0003` | seal | The record would carry a secret value, an env value or personal data; nothing is written | Remove the value from what is sealed |
| `MAIN-SEAL-0004` | verify | The signature is valid but the signer isn't one of `seal.signers` or the given `--key` or `--identity` | Verify with the expected signer, or add it to `seal.signers` |
| `MAIN-SEAL-0005` | seal | A file can't go into the build hash: a symlink leaving the roots, an unreadable file, a path with CR or LF, or a missing root | Fix or exclude the file the error names |
| `MAIN-SEAL-0006` | check | `check --env prod` with `seal.mode: off` | Turn sealing on for production |
| `MAIN-SEAL-0007` | verify | The record's build hash doesn't match the files of the folder given to `seal verify` | Verify the folder that was sealed |
| `MAIN-SEAL-0008` | seal diff | A sensitive capability is new since the old seal: a call of a new sensitive kind, a new sensitive call, a widened grant, or a new destructive action | Review the change; a person accepts it |

## REALTIME

Spec `realtime`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-REALTIME-0001` | runtime | Subscribe with no session (401) | Sign the person in first |
| `MAIN-REALTIME-0002` | runtime | Subscribe refused: access denied, or a `user:` channel that isn't the caller's (403) | Subscribe to a channel the person may read |
| `MAIN-REALTIME-0003` | runtime, check | A channel prefix not declared under `realtime.channels` (404 on subscribe, a throw on publish; a check on a literal in code) | Declare the prefix under `realtime.channels` |
| `MAIN-REALTIME-0004` | runtime | Event data is not JSON, or is larger than `max-event` | Send JSON under the size limit |
| `MAIN-REALTIME-0005` | runtime | A channel or event name doesn't match its pattern | Use the pattern the error shows |
| `MAIN-REALTIME-0006` | check, runtime | The `local` driver in production without `single-instance: true` | Use a shared driver, or set `single-instance: true` for one instance |
| `MAIN-REALTIME-0007` | check | `max-event` plus the 4KB envelope is larger than `events.broadcast.max-payload` | Lower `max-event`, or raise `events.broadcast.max-payload` |
| `MAIN-REALTIME-0008` | runtime | A stream was closed because its reader fell more than `buffer` behind (logged) | Reconnect; read faster or raise `buffer` |
| `MAIN-REALTIME-0009` | runtime | The person already has `per-user` open streams (429) | Close another stream, or raise `per-user` |
| `MAIN-REALTIME-0010` | runtime | WebSocket upgrade refused: the `Origin` is neither the app's own nor in `inbound.cors.origins` (403) | Add the origin to `inbound.cors.origins` |
| `MAIN-REALTIME-0011` | runtime | WebSocket upgrade refused: the ticket is unknown, expired, used or from another tenant (401) | Get a fresh ticket with `realtime.ticket()` right before connecting |
| `MAIN-REALTIME-0012` | runtime, check | A client message or stream refused: no `send` action on the prefix, access denied, or no handler | Declare `send` under `realtime.channels.<prefix>` and register `realtime.on` |
| `MAIN-REALTIME-0013` | runtime | A client message isn't JSON, has an unknown type, is over `max-message` or fails the handler's schema | Send JSON that matches the handler's schema |
| `MAIN-REALTIME-0014` | runtime | Client messages over `realtime.socket.rate` | Send less often, or raise the rate on purpose |
| `MAIN-REALTIME-0015` | check | `realtime.transports` lists `websocket` on an adapter or platform without HTTP upgrade | Use `sse`, or a server adapter with upgrade support |
| `MAIN-REALTIME-0016` | runtime, check | A binary stream refused: prefix not under `realtime.streams`, type not listed, or `max-per-socket` reached | Declare the prefix and type under `realtime.streams` |
| `MAIN-REALTIME-0017` | runtime | A stream passed its byte `budget`, or a frame passed `max-frame`; the stream or socket is closed | Send smaller frames, or raise the budget on purpose |

## WORKFLOW

Spec `workflows`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-WORKFLOW-0001` | runtime | `step`, `sleep`, `waitFor` or `approve` called outside a workflow run (500) | Call it inside a workflow function |
| `MAIN-WORKFLOW-0002` | runtime | On resume, the code reached a step the journal doesn't have in that place (code changed under a live version); the run stops as `stuck` | Ship the change as a new workflow version |
| `MAIN-WORKFLOW-0003` | runtime | No registered code for the run's workflow version; the run stops as `stuck` | Register the version the run started on |
| `MAIN-WORKFLOW-0004` | runtime | A step result or workflow input is not JSON, or is larger than `max-step-result` | Return JSON under the size limit |
| `MAIN-WORKFLOW-0005` | runtime | A step failed after its last retry; the run is `failed` | Fix the cause and start a new run |
| `MAIN-WORKFLOW-0006` | runtime | No run with that id in the current tenant (404) | Use an id from this tenant |
| `MAIN-WORKFLOW-0007` | runtime | The journal store is unreachable, so the run was not started (503, retryable) | Retry once the store is back |
| `MAIN-WORKFLOW-0008` | runtime | Cancel of a run that has already finished (409) | None; the run is done |
| `MAIN-WORKFLOW-0009` | runtime, check | A duration is not a valid `<n><s\|m\|h\|d>` value, or is over 365d | Write a duration such as `30m` |
| `MAIN-WORKFLOW-0010` | check | A clock, random or network call (`Date.now`, `new Date()`, `Math.random`, `crypto.randomUUID`, `http.*`, `fetch`) in a workflow function outside a step | Move the call into a `step` |
| `MAIN-WORKFLOW-0011` | check, runtime | The `local` driver in production | Use a database driver in `main.env.prod.yaml` |
| `MAIN-WORKFLOW-0012` | check | Two workflow definitions with the same name and version | Give each definition its own name and version |

## APPS

Spec `app-registry`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-APPS-0001` | runtime | The registry folder is unsafe (world-writable, or owned by another user and not root) or not writable; nothing is written and the app keeps serving | Fix the folder's owner and mode |
| `MAIN-APPS-0002` | CLI | Two records claim one project id from different repositories | Give the copied app a new id with `mainsdk init --new-id` |
| `MAIN-APPS-0003` | CLI | A record says running but was last seen more than 5 minutes ago | Restart the app, or remove the stale record |
| `MAIN-APPS-0004` | check | Code reads the registry folder directly, or `permissions.disk` grants it, instead of `apps.peer()` | Use `apps.peer()` |
| `MAIN-APPS-0005` | check | A file that reads `apps.peer()` or `apps.call()` results also makes an outbound call; registry data may leave the machine | Split the code so peer data stays local |
| `MAIN-APPS-0006` | runtime | A peer call between apps that don't both list each other under `apps.peers` | List each app under the other's `apps.peers` |
| `MAIN-APPS-0007` | runtime | A peer call to an action the callee doesn't list under `apps.expose` | List the action under the callee's `apps.expose` |
| `MAIN-APPS-0008` | runtime | The link handshake failed: the peer's proof doesn't verify with the identity key in its seal, or its seal is invalid | Re-seal the peer and check its identity key |
| `MAIN-APPS-0009` | runtime | `apps.link: on` without `apps.identity` and `MAINSDK_APP_KEY`; the link stays off | Set `apps.identity` and `MAINSDK_APP_KEY` |

## ADOPT, ASSURE and CLOUD

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-ADOPT-0001` | CLI | `adopt next` before key flows are locked | Run `mainsdk adopt lock` first |
| `MAIN-ASSURE-0003` | CLI | The record `assure` read from a URL has an invalid signature (exit 2) | Treat the app's record as untrusted |
| `MAIN-CLOUD-0402` | Cloud (phase 2) | Free allowance used, after the warning and grace period. Only the Cloud answers it; your app keeps running | Add a card with a cap, or move to Teams |

## MEM

Agent memory (spec `memory`, planned for 0.4).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-MEM-0001` | runtime | No subject: `about` is missing and the call has no `on_behalf_of` or session user (400) | Pass `about`, or call inside a session or an agent call made for a person |
| `MAIN-MEM-0002` | runtime | No memory with that id in the current tenant, app and scope (404, same body either way) | Use an id returned in this tenant and app |
| `MAIN-MEM-0003` | runtime | The injection check flagged the text of a write; nothing was stored (422) | Store what the person said, not instructions from a tool or page |
| `MAIN-MEM-0004` | runtime | A recalled memory was flagged by the injection check and left out of the context (logged) | Review the memory and `forget` it if it is an injection |
| `MAIN-MEM-0005` | runtime | The agent has no memory grant for this verb, or `forget: deny` (403) | Add `read` or `write` under `agents.<name>.memory` on purpose |
| `MAIN-MEM-0006` | runtime | The agent is over its memory `recalls` or `writes` per day (429) | Wait for the day to reset, or raise the limit on purpose |
| `MAIN-MEM-0007` | runtime | Forget refused: a legal hold applies to the person (409) | Lift the hold with the person who set it, then forget |
| `MAIN-MEM-0008` | runtime | A children's rule refused it: children are off, no guardian consent, or a provider model would extract (403) | Set `children: guardian` and record the guardian's consent; use a local extract model |
| `MAIN-MEM-0009` | runtime | Invalid input: unknown kind, bad duration, `pan` label, `k` over 100, `hops` over 2 or a bad predicate (400) | Fix the argument the problem's `errors` member names |
| `MAIN-MEM-0010` | runtime | Revise of a version that is no longer current (409) | Read the current version with `memory.history` and revise that |
| `MAIN-MEM-0011` | runtime | Import refused: a line is malformed, or personal or non-procedure memory would cross a tenant or app (422) | Import into the same tenant and app, or export only `procedure` memories labelled `none` |
| `MAIN-MEM-0012` | runtime | The driver doesn't declare the capability the call needs, such as `asOf`, `hops` or `relate` (501) | Drop the option, or use a driver that declares the capability |
| `MAIN-MEM-0013` | runtime | The memory store is unreachable (503, retryable); `context` degrades to an empty block | Retry; check the store and its region endpoint |
| `MAIN-MEM-0014` | runtime | An Anthropic memory tool path is outside `/memories/` or tries to traverse (400) | Keep paths under `/memories/` with no `..` or encoded separators |
| `MAIN-MEM-0015` | runtime | A driver hasn't confirmed the erase yet; no receipt is issued and the erase keeps retrying (503) | Wait for the retry job; the receipt follows the driver's confirmation |
| `MAIN-MEM-0016` | runtime | A write from a tool, MCP, the web or an import was refused by `from-tools: refuse` (403) | Ask the person to confirm the fact, or set `from-tools: quarantine` |
| `MAIN-MEM-0020` | check | A driver that only soft-deletes holds memories that may be personal | Use a driver with `erase: hard`, such as `db` |
| `MAIN-MEM-0021` | check | A region the app serves has no endpoint in the memory driver | Add the region's endpoint, or use the `db` driver in that region |
| `MAIN-MEM-0022` | check | Recalled memory is passed as the `system` text of an `ai` call | Pass `memory.context()` text in a user message as data |
| `MAIN-MEM-0023` | check | A driver is named `memory`; the in-process driver is `local` (ADR-0039) | Rename the driver to `local` |
| `MAIN-MEM-0024` | check | `children: guardian` with an extract model on a provider | Use a local extract model, or turn children off |
| `MAIN-MEM-0025` | check | The `local` memory driver in production | Use the `db` driver or a provider driver in production |

## PORT and SDK

Portable core (spec `portable-core`, planned for 0.4) and SDK conventions (spec `sdk-conventions`, planned for 0.3).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-PORT-0001` | check | `main.yaml` uses an interface or driver that the declared `targets.<name>.runtime` can't run, such as `disk` on `workerd` | Move that work to a target on Node, Bun or Deno, or drop the interface from this target |
| `MAIN-PORT-0002` | runtime | A call reached the portable fallback of an adapter-only interface on a runtime without it | Call it from a server target on Node, Bun or Deno |
| `MAIN-PORT-0003` | runtime | A portable global the call needs is missing, such as `crypto.subtle` on an old runtime | Upgrade the runtime to one that implements the WinterTC Minimum Common API |
| `MAIN-SDK-0001` | runtime | The call was aborted through its `signal`; `cause` is the signal's reason. Never retried | Nothing to fix if the abort was meant; otherwise don't abort the signal |
| `MAIN-SDK-0002` | check | Code for a production target imports `mainsdk/experimental/*` (a warning) | Use the stable subpath once the interface ships, or accept the risk on purpose |

## API

Spec `app-api`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-API-0001` | runtime (start) | An action's HTTP mapping is invalid: a `GET` on a write or destructive action, a path parameter that isn't a top-level string or integer input key, a nested field on a `GET` or `DELETE`, two actions on one method and path, or a name segment that isn't an identifier (500) | Fix the mapping the error names: reads use `GET`, path parameters are top-level inputs |
| `MAIN-API-0002` | runtime | An `Idempotency-Key` was reused with a different input (422) | Send a new `Idempotency-Key` for a new request |
| `MAIN-API-0003` | runtime | The first request with this `Idempotency-Key` is still running (409, retryable) | Wait for the first request to finish, then retry |
| `MAIN-API-0004` | runtime | An action returned a value that fails its `output` schema; nothing of it is sent (500) | Return a value that matches the `output` schema |
| `MAIN-API-0005` | runtime | A risk listed under `api.idempotency.require` was called without `Idempotency-Key` (400) | Send an `Idempotency-Key` header with the call |
| `MAIN-API-0006` | runtime | The major version was called after its `sunset` date (410) | Move the client to the current major version |
| `MAIN-API-0007` | client | The generated client got no answer, or an answer that isn't problem details or JSON (retryable for network failures) | Check the URL and the network; retry network failures |
| `MAIN-API-0010` | check | An action's input or output has no JSON Schema (a foreign schema without `toJSONSchema()`); the document and client type it as unknown | Use a schema with `toJSONSchema()`, or a native one from `mainsdk/schema` |
| `MAIN-API-0011` | check | The committed snapshot at `api.snapshot` differs from what the code generates | Run `mainsdk api openapi` and commit the new snapshot |
| `MAIN-API-0012` | check, CLI | `mainsdk api diff` found a breaking change in a major version that already shipped | Ship the change in a new major version, and keep the shipped one working |

## IMPORT

Spec `imports`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-IMPORT-0001` | runtime | The format or encoding isn't supported: not CSV, XLSX, JSON or NDJSON, not UTF-8, a JSON value that isn't an array, a legacy `.xls` or an encrypted workbook (415) | Convert the file to CSV, XLSX, JSON or NDJSON in UTF-8 |
| `MAIN-IMPORT-0002` | runtime | The file is over a limit: `max-rows`, `max-columns`, `json-max` or the `files` size (413); rows up to the limit are not written | Split the file, or raise the limit under `imports` |
| `MAIN-IMPORT-0003` | runtime | The mapping is incomplete or unconfirmed: a required field has no column, a mapped column doesn't exist, or a field would come from a model suggestion not passed back in `mapping` (422) | Map every required field to a column, and confirm the suggested mapping |
| `MAIN-IMPORT-0004` | runtime | The file isn't `ready` yet (still scanning) (409, retryable) | Wait for the scan to finish, then retry |
| `MAIN-IMPORT-0005` | runtime | The run stopped because failed rows passed `maxErrors`; the report lists them (422) | Fix the rows the report lists, then run again |
| `MAIN-IMPORT-0006` | runtime | An unsafe workbook: a zip entry over the size or ratio limit, a path outside the archive, or XML with a `DOCTYPE` or entity (422) | Save the workbook again without the flagged parts |
| `MAIN-IMPORT-0010` | runtime (logged) | A pull failed: the source was unreachable or refused; the cursor is unchanged and the next run retries | Check the source's address and credentials; the next run retries |
| `MAIN-IMPORT-0011` | runtime (logged) | The deletion guard tripped: a full pass returned fewer keys than `deletes-guard`, so nothing was deleted | Check the source; raise `deletes-guard` only on purpose |
| `MAIN-IMPORT-0012` | runtime (logged) | The source rejected the stored cursor; a full pass is scheduled | Nothing to fix; the full pass runs |
| `MAIN-IMPORT-0020` | check | A source under `imports.sources` has no `imports.source()` in the code, or the code defines a source `main.yaml` doesn't declare | Declare each source in both `main.yaml` and the code |

## CONN

Spec `connections`. The MCP codes that the connections spec adds are under [AI, MCP and actions](#ai-mcp-and-actions).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-CONN-0001` | runtime | The provider isn't under `connections.providers` (500 at start for config, 400 for a call) | Declare the provider under `connections.providers` |
| `MAIN-CONN-0002` | runtime | No active connection to this provider for this person or tenant (403); the fix names `connections.connect` | Ask the person to connect with `connections.connect` |
| `MAIN-CONN-0003` | runtime | The connection wasn't granted the scope this call needs (403); the fix asks to connect again with it | Ask the person to connect again with that scope |
| `MAIN-CONN-0004` | runtime | The agent may not use this scope: it isn't under `agents.<name>.connections.<provider>` (403); nothing is sent | Add the scope under `agents.<name>.connections.<provider>` |
| `MAIN-CONN-0005` | runtime | The URL's host isn't one of the provider's hosts, or isn't `https`; the token is not sent (403) | Call an `https` host the provider lists under `hosts` |
| `MAIN-CONN-0006` | runtime | The callback was refused: state missing, unknown, expired, used or from another session, code verifier rejected, or issuer mismatch (400) | Start the connect flow again |
| `MAIN-CONN-0007` | runtime | The connection expired or was revoked at the provider (`invalid_grant`), or its key was destroyed; connect again (401) | Ask the person to connect again |
| `MAIN-CONN-0008` | runtime | The provider couldn't be reached to refresh an expired token (503, retryable) | Retry when the provider is reachable |
| `MAIN-CONN-0009` | runtime | `connect` asked for a scope beyond `providers.<name>.scopes` (400); nothing is sent | Request only scopes listed under `providers.<name>.scopes` |
| `MAIN-CONN-0020` | check | An agent or `step-up` names a scope not under its provider's `scopes`, or a provider not under `connections.providers` | Name only scopes and providers declared under `connections` |
| `MAIN-CONN-0021` | check | A provider has no preset and no `hosts`, so no call could be sent | Use a `preset`, or list the provider's `hosts` |

## SEED and PREVIEW

Spec `seed-preview`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SEED-0001` | runtime | Seed or fixtures refused: the resolved environment is production (nothing is opened or written) | Run seed and fixtures outside production |
| `MAIN-SEED-0002` | runtime | Seed refused: the target database is not seedable (not local, not a preview, no seedable marker) | Seed a local or preview database that carries the seedable marker |
| `MAIN-SEED-0003` | runtime | A field can't be generated from its schema (an unsupported pattern or a `refine`); set a generator under `seed.models` | Set a generator under `seed.models` for that field |
| `MAIN-SEED-0004` | runtime | AI text unavailable or over `seed.ai.limit`; built-in text was used and the run went on | Nothing to fix; raise `seed.ai.limit` or check the AI driver if you want AI text |
| `MAIN-PREVIEW-0001` | runtime | The db driver has no branching capability; use `preview.driver: local` or a driver that has it | Use `preview.driver: local`, or a db driver with branching |
| `MAIN-PREVIEW-0002` | runtime | The provider refused or failed while making the preview; what was made was deleted | Check the provider's status and credentials, then retry |
| `MAIN-PREVIEW-0003` | runtime | Refused to delete or seed the parent, or a database the preview driver did not make | Point the preview at a database it made |
| `MAIN-SEED-0010` | check | `seed` or `preview` is active in production, or app code outside tests and scripts imports the seed engine | Keep seed and preview out of production; import the seed engine only in tests and scripts |
| `MAIN-SEED-0011` | check | A literal under `seed.models` looks like real personal data (an email outside the reserved domains, a phone number outside the reserved ranges) | Use reserved example values, such as `example.com` emails and reserved phone ranges |

## ENGAGE

Spec `engagement`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-ENGAGE-0001` | runtime | Engagement message skipped: the person reached the weekly limit | Nothing to fix; the message waits for next week |
| `MAIN-ENGAGE-0002` | runtime | Engagement messages stopped for this person: `stop-after-ignored` messages in a row were ignored | Nothing to fix; the person can opt back in |
| `MAIN-ENGAGE-0003` | runtime | AI copy was refused by the copy rules, was over the tenant's `copy.limit`, or failed; the template text was used | Nothing to fix; raise `copy.limit` or fix the copy rules if you want AI copy |
| `MAIN-ENGAGE-0004` | runtime | Guardian control refused: the caller isn't the child's guardian, or the change loosens a limit (403) | Ask the child's guardian to make the change |
| `MAIN-ENGAGE-0005` | runtime | Not sent to a children's audience: the copy has streak-loss or guilt pressure, or comparative social proof | Remove streak-loss, guilt pressure and comparative social proof from the copy |
| `MAIN-ENGAGE-0006` | runtime | `urgent: true` on an engagement message refused; engagement never skips quiet hours (400) | Remove `urgent: true` |
| `MAIN-ENGAGE-0007` | runtime | A social proof placeholder had no declared query, or its result was hidden or empty; the text without proof was used | Declare a query for the placeholder, or accept the text without proof |
| `MAIN-ENGAGE-0008` | runtime | A guardrail value in `main.yaml` is invalid (start fails), or a pushed value loosens one (refused, last good kept) | Fix the guardrail value in `main.yaml` |
| `MAIN-ENGAGE-0010` | check | Confirmshaming in unsubscribe or opt-out copy | Write neutral unsubscribe copy |
| `MAIN-ENGAGE-0011` | check | Social proof not backed by data: a literal count or name ("1,240 people finished today") instead of a `{{proof.*}}` placeholder | Use a `{{proof.*}}` placeholder backed by a declared query |
| `MAIN-ENGAGE-0012` | check | Engagement messages are sent (`journey`, `ladder`, `engagement.send` or an engagement category) with no `notify.engagement.max-per-week` | Set `notify.engagement.max-per-week` |
| `MAIN-ENGAGE-0013` | check | A children's audience is possible with no `notify.engagement.guardian` settings | Set `notify.engagement.guardian` |
| `MAIN-ENGAGE-0014` | check | Copy that can reach a children's audience has streak-loss or guilt pressure, or comparative social proof | Remove streak-loss, guilt pressure and comparative social proof from that copy |

## SEARCH

Spec `search`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SEARCH-0001` | runtime | The index isn't declared under `search.indexes` (400) | Declare the index and its fields under `search.indexes` |
| `MAIN-SEARCH-0002` | runtime | The access filter for this searcher can't be expressed in the engine's query; refused, never post-filtered (403) | Use an access driver that lists for this resource type, or store the fields the filter needs in the index |
| `MAIN-SEARCH-0003` | runtime | `search.query` without `for`, outside `tenant.system` (400) | Pass the searcher as `for` |
| `MAIN-SEARCH-0004` | runtime | The engine is unreachable or the query passed `timeout` (503, retryable); index changes stay queued | Retry; restore the engine; changes apply when it is back |
| `MAIN-SEARCH-0005` | runtime | A filter, sort or facet names a field not declared for it, or a reserved field (`_tenant`, `_region`, `_v`) (400) | Declare the field as `filter`, `sort` or `facet`; never filter on reserved fields |
| `MAIN-SEARCH-0006` | runtime | No index endpoint for the tenant's region; the change stays queued and is sent nowhere else (logged) | Add an endpoint for that region under the driver's `regions` |
| `MAIN-SEARCH-0007` | runtime | A cursor would go past `max-depth` (400) | Refine the query or filters |
| `MAIN-SEARCH-0008` | runtime | `q` is longer than 512 characters, or a filter value has the wrong type for its field (400) | Shorten the query or send a value of the field's type |
| `MAIN-SEARCH-0009` | runtime | An index change failed after its last retry and is in the dead-letter queue; counted in `search.status` | Read the dead-letter entry, fix the cause and run `mainsdk search reindex` |
| `MAIN-SEARCH-0010` | check | An index's access filter needs a field the index doesn't store, or the access driver's profile can't list for that resource type | Add the field to the index, or use an access driver that lists |
| `MAIN-SEARCH-0011` | check | A field labelled `sensitive`, `phi`, `child` or `secret` is indexed without `index: allow` on the field | Remove the field from the index, or add `index: allow` with a reason |
| `MAIN-SEARCH-0012` | check | An engine driver has no endpoint for a region the app stores data in | Add an endpoint per region under the driver's `regions` |
| `MAIN-SEARCH-0013` | check | An engine SDK (`typesense`, `meilisearch`, `algoliasearch`) imported outside a driver | Call `search` instead |
| `MAIN-SEARCH-0014` | check | `search.query` without `for` in a file outside `tenancy.system.allow` | Pass the searcher as `for` |

## FEED

Spec `feeds`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-FEED-0001` | runtime | Follow, request or profile read refused: one side blocks the other (403) | None; the block stands until it is removed |
| `MAIN-FEED-0002` | runtime | A follow or item across tenants (403) | Keep follows and items inside one tenant |
| `MAIN-FEED-0003` | runtime | The item doesn't exist, is removed, or isn't visible to the viewer (404) | Use an id the viewer may see |
| `MAIN-FEED-0004` | runtime | Edit or remove by someone who isn't the author and whom `access` doesn't allow `feeds.remove` (403) | Let the author act, or grant `feeds.remove` to moderators |
| `MAIN-FEED-0005` | runtime | Following more than `max-following` (422) | Unfollow someone first |
| `MAIN-FEED-0006` | runtime | A fan-out batch failed after its last retry and is in the dead-letter queue; affected timelines are served by merging at read time (logged) | Fix the cause and retry the dead-letter entry |
| `MAIN-FEED-0007` | runtime | The ranker threw, returned an entry without a reason, or passed `ranked.budget`; the chronological timeline was served (logged) | Fix the ranker so it returns a reason for every entry within the budget |
| `MAIN-FEED-0008` | runtime | A pushed value loosens `page.end`, `page.pause_after`, `trending.min-count` or `max-following`; refused, last good kept | Push only tighter values, or change `main.yaml` in a reviewed deploy |
| `MAIN-FEED-0010` | check | A feed with no end: `page.end: false`, `page.pause_after` off or above 500, or a client that requests the next page with no user action | Keep `page.end: true`, set `pause_after` to 500 or less, and load more only on a person's action |
| `MAIN-FEED-0011` | check | `timeline.order: ranked`, or a `feeds.ranker`, in an app with a children's audience and no chronological-only rule for it | Serve children the chronological timeline |
| `MAIN-FEED-0012` | check | `trending.min-count` below 10, or a trending key built from a labelled field | Raise `min-count` to 10 or more; build keys from tags or item ids |
| `MAIN-FEED-0013` | check | `fanout.threshold` above 100,000, `timeline.max` above 5,000 or `max-following` above 50,000 | Lower the value to its ceiling |

## MOD

Spec `moderate`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-MOD-0001` | runtime | Report refused: the person passed `reports.per-user`, or already reported this target (429) | None; the person can report again later |
| `MAIN-MOD-0002` | runtime | Unknown reason, or the target doesn't exist in the current tenant (400) | Use a reason from `moderate.reasons` and a target in this tenant |
| `MAIN-MOD-0003` | runtime | The caller lacks `moderate.review`, or the case is assigned to someone else (403) | Grant `moderate.review`, or assign the case to the caller |
| `MAIN-MOD-0004` | runtime | Appeal refused: outside `appeals.window`, already appealed, or the decision isn't the caller's to appeal (409) | None; one appeal per decision, by its author, within the window |
| `MAIN-MOD-0005` | runtime | An appeal resolved by the reviewer who made the decision (403) | Assign the appeal to another reviewer |
| `MAIN-MOD-0006` | runtime | A pre-screen driver is unreachable or failed; the content stays held and is retried, then queued for people after `hold.max` (logged) | Restore the driver; held content clears when it is back |
| `MAIN-MOD-0007` | runtime | Known-abuse hash match: the content is blocked and never published; logged with the list name, never the content | Follow your legal duty through the `onMatch` handler |
| `MAIN-MOD-0008` | runtime | A decision other than `none` without a ground or facts (400) | Name the terms clause or law and the facts |
| `MAIN-MOD-0009` | runtime | Held, blocked or removed content read through `files.url`, `media.url` or `feeds` (403) | Wait for the pre-screen to clear it |
| `MAIN-MOD-0010` | check | A hash list or hash database in the repository or the build output | Delete it; fetch lists from your provider at run time under `prescreen.hash.lists` |
| `MAIN-MOD-0011` | check | User content is published (`feeds.publish`, `share` of an upload, a public file URL) with no `moderate` section | Add a `moderate` section with `hold` and `reports` |
| `MAIN-MOD-0012` | check | No `moderate.reports.per-user`, or one above 100 an hour | Set `reports.per-user` to 100 an hour or less |
| `MAIN-MOD-0013` | check | `appeals` off or a window under 6 months, or `remove-on` lists a label other than `spam` | Keep appeals on for at least 6 months; send other labels to `hold-on` |

## MEDIA

Spec `media`.

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-MEDIA-0001` | runtime | The source file isn't `ready`, doesn't exist in the current tenant, or the caller may not read it (404) | Complete the upload first and pass a file the caller may read |
| `MAIN-MEDIA-0002` | runtime | The source is over a limit: duration, size or pixels; the job failed in the probe step, nothing was transformed (422) | Ask for a smaller file, or raise the limit up to its ceiling |
| `MAIN-MEDIA-0003` | runtime | The source's magic bytes don't match a supported type, or don't match its declared type (415) | Upload a supported image, video or audio file |
| `MAIN-MEDIA-0004` | runtime | The driver doesn't support this kind or format, such as an image on `mux` (501) | Use a driver whose profile lists the kind |
| `MAIN-MEDIA-0005` | runtime | A transform step failed after its last retry: the provider failed, or `ffmpeg` exited non-zero; the job is `failed` | Read the step's error and start a new job |
| `MAIN-MEDIA-0006` | runtime | No job with that id in the current tenant (404) | Use a job id from this tenant |
| `MAIN-MEDIA-0007` | runtime, check | `media.keep` lists `gps`, `location` or an unknown metadata name (start fails; check finding) | Keep only `icc` and `orientation-tag` |
| `MAIN-MEDIA-0010` | check, runtime | The `ffmpeg` driver in production | Use `getqr`, `mux` or `cloudinary` in `main.env.prod.yaml` |
| `MAIN-MEDIA-0011` | check | An image or video library (`sharp`, `jimp`, `fluent-ffmpeg`, `@ffmpeg/ffmpeg`, `ffmpeg-static`) or an `ffmpeg` program run outside a driver | Call `media` instead |
| `MAIN-MEDIA-0012` | check | `delivery: provider` on `mux` or `cloudinary`: outputs served by the provider, outside `files` (named gap) | Use `delivery: files`, or accept the gap |
| `MAIN-MEDIA-0013` | check | A media kind used with no limits, or a limit above its ceiling: `max-duration` over 4h, `max-size` over 10GB, `max-pixels` over 100MP | Declare limits for each kind within the ceilings |


## METER and LIMIT

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-METER-0001` | runtime, check | A metric not declared under `meter.metrics` | Declare the metric with its unit and aggregate |
| `MAIN-METER-0002` | runtime | A value that isn't finite, is negative for `sum` or `count`, or an `at` outside its window (400) | Record a valid value at a time within 35 days back and 1 hour ahead |
| `MAIN-METER-0003` | runtime | The buffer was full while the store was down, so the oldest records were dropped (logged with the count) | Restore the store; raise `meter.buffer` if outages are long |
| `MAIN-METER-0004` | runtime | Usage was served from the last known value because the store can't be reached (`stale: true`) | Restore the store |
| `MAIN-METER-0005` | runtime | An export to `pay` failed for a tenant and hour; retried with the same identifier | Check the pay driver and the provider's meter name |
| `MAIN-METER-0006` | check, runtime | `meter` is invalid: unknown aggregate, `unique` without `of`, an exported metric with no provider meter, `keep` under 35 days, or `local` in production | Fix the key the finding names |
| `MAIN-METER-0007` | runtime | No meter store for the tenant's region; the record is refused, never written elsewhere | Add a store for that region under `meter` |
| `MAIN-METER-0008` | runtime | A usage window is invalid: `from` after `to`, not on whole hours, or over 13 months (400) | Pass a calendar window or a whole-hour range |
| `MAIN-LIMIT-0001` | runtime | The rate limit for this policy and key is reached (429, with `Retry-After`) | Wait `Retry-After` seconds |
| `MAIN-LIMIT-0002` | runtime | The quota for this window is used up (429, with `Retry-After`) | Wait for the window to reset |
| `MAIN-LIMIT-0003` | runtime | No concurrency slot came free within `wait` (429, with `Retry-After`) | Retry later, or raise `max` on purpose |
| `MAIN-LIMIT-0004` | runtime | The lock wasn't acquired within `wait` (409, retryable) | Retry, or pass a longer `wait` |
| `MAIN-LIMIT-0005` | runtime | Refused because the store is down and the policy's `on-store-down` is `closed` (503, with `Retry-After`) | Restore the limits store |
| `MAIN-LIMIT-0006` | runtime, check | A policy, quota or concurrency name not declared under `limits` | Declare it under `limits` |
| `MAIN-LIMIT-0007` | check, runtime | A policy is invalid: `max` under 1, a bad `per`, an unknown algorithm or key, `burst` under `max`, or a `ttl` over 1 hour | Fix the key the finding names |
| `MAIN-LIMIT-0008` | check, runtime | The `local` limits driver in production without `single-instance: true` | Use `redis`, or set `single-instance: true` for one instance |
| `MAIN-LIMIT-0009` | runtime | A lock or concurrency lease expired before the work finished; its signal was aborted (logged) | Raise `ttl`, or check the store's health |

## COMPUTE

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-COMPUTE-0001` | runtime, check | A target not declared under `compute.targets` | Declare the target |
| `MAIN-COMPUTE-0002` | runtime | Refused before submit: the worst case (price times timeout) passes `maxCost`, a `compute.limits` ceiling or the agent's budget (402) | Lower the timeout, raise `maxCost` on purpose, or wait for the period |
| `MAIN-COMPUTE-0003` | runtime | The running cost reached `maxCost`; the job was cancelled at the provider | Raise `maxCost` on purpose, or make the job cheaper |
| `MAIN-COMPUTE-0004` | runtime | No heartbeat for three periods; the job is `lost` and was cancelled at the provider | Check the provider; start the job again |
| `MAIN-COMPUTE-0005` | runtime | The provider failed submit, status or cancel after retries (502) | Check the provider's status and your account |
| `MAIN-COMPUTE-0006` | runtime | The job passed its timeout and was cancelled | Raise the target's timeout on purpose |
| `MAIN-COMPUTE-0007` | runtime | Labelled input to a target outside the tenant's region (403) | Use a target in the tenant's region |
| `MAIN-COMPUTE-0008` | check | A target isn't pinned: no model version, app or endpoint id | Pin the version or id |
| `MAIN-COMPUTE-0009` | runtime | An output is too large or of a type not in `compute.results.types` (413 or 415) | Raise the limit or allow the type on purpose |
| `MAIN-COMPUTE-0010` | runtime | No job with that id in the current tenant (404) | Use an id from `compute.list` |
| `MAIN-COMPUTE-0011` | runtime | Cancel of a finished job (409) | Nothing to cancel |
| `MAIN-COMPUTE-0012` | runtime | A provider callback failed verification (400) | Check the provider's webhook secret |
| `MAIN-COMPUTE-0013` | check, runtime | A target has no `price` or `timeout`, or a timeout over 24h | Set both, with a timeout of 24h or less |

## MAIL and CAL

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-MAIL-0001` | runtime | No mailbox or route matches the recipient; dropped and logged | Add a mailbox or a `mail.on` route for the address |
| `MAIN-MAIL-0002` | runtime | A raw message can't be parsed, or passes the size, part or nesting limit | Nothing to fix in code; the record keeps the headers |
| `MAIN-MAIL-0003` | runtime | Rejected by `mail.reject`: DMARC failed or a virus was found | Nothing to fix; the sender's domain or file is the problem |
| `MAIN-MAIL-0004` | runtime | An attachment was refused by size, type or scan; a placeholder is kept | Raise `mail.attachments.max-size` on purpose if needed |
| `MAIN-MAIL-0005` | runtime | A reply address token is invalid, expired or for another tenant; threaded by headers instead | Nothing to fix; raise `mail.reply.expires` if replies come late |
| `MAIN-MAIL-0006` | runtime | An IMAP or JMAP server failed or timed out during a pull; retried | Check the provider's status |
| `MAIN-MAIL-0007` | runtime | A mailbox's cursor can't be continued; it is pulled again from the start | Nothing to do |
| `MAIN-MAIL-0008` | check, runtime | `mail` is invalid: a mailbox outside `domains`, an inbound provider with no secret, or a pull provider not under `connections.providers` | Fix the key the finding names |
| `MAIN-MAIL-0009` | check | Code listens for SMTP: a server on port 25, 465 or 587, or an SMTP server package | Receive mail through `mail` and a provider webhook (ADR-0052) |
| `MAIN-MAIL-0010` | runtime | An `Authentication-Results` header from a server other than the provider's was ignored | Nothing to fix; it may be a spoofing attempt |
| `MAIN-CAL-0001` | runtime, check | An event is invalid: end before start, an unknown IANA zone, a date-time mixed with a date, or no title (400) | Fix the field the error names |
| `MAIN-CAL-0002` | runtime, check | A recurrence rule is invalid or uses an unsupported part (400) | Use the parts the calendar page lists |
| `MAIN-CAL-0003` | runtime | A window passes `max-window`, or the expansion passes `max-occurrences` (400) | Ask for a shorter window |
| `MAIN-CAL-0004` | runtime | iCalendar text can't be parsed at a line; that event is skipped | Fix the line, or accept the skip |
| `MAIN-CAL-0005` | runtime | An import is larger than `calendar.max-import` (413) | Split the file, or raise the limit on purpose |
| `MAIN-CAL-0006` | runtime | No calendar with that id in the tenant, or access denies it (404 or 403) | Use a calendar the person may read |
| `MAIN-CAL-0007` | runtime | An edit scope that doesn't fit the event or occurrence (400) | Use `all` for a single event, and an occurrence from the series |
| `MAIN-CAL-0008` | runtime | The event changed since `version` was read (409) | Read it again and reapply the change |

## INCIDENT

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-INCIDENT-0001` | runtime | Switched off by an incident control (503, retryable) | Wait for the control to clear, or clear it with `mainsdk incident off` |
| `MAIN-INCIDENT-0002` | runtime | The app is read-only during an incident (503 for requests; thrown by writes) | Wait for `mainsdk incident off read-only`, or use a path in `read-only-allow` |
| `MAIN-INCIDENT-0003` | runtime | The session was issued before the incident sign-out cut-off (401) | Sign in again |
| `MAIN-INCIDENT-0004` | check, runtime | A kill target is unknown or malformed, or names a protected interface | Name an existing action, route, interface, driver or agent |
| `MAIN-INCIDENT-0005` | runtime | `mainsdk incident` could not write: no `--reason`, or the config driver has no `write` | Pass `--reason`, or use a config driver with `write` and set the key by hand |
| `MAIN-INCIDENT-0006` | runtime | `incident.set` refused: no `incident.manage`, or no fresh phishing-resistant session (403) | Grant `incident.manage`, and sign in again with a passkey |
| `MAIN-INCIDENT-0007` | check, runtime | A control with no `expires` has been in force for 24 hours (warn) | Add `--expires` to the control, or clear it when it is no longer needed |

## PROTECT

Codes from protected files (spec `protect-taps`, planned for 0.4). Runtime codes are also listed in [errors](https://mainsdk.dev/docs/reference/errors).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-PROTECT-0001` | runtime | Licence denied by the policy (403); the TAPS error type is in `taps`, the failed condition only in the decision log | Check the asset's policy with `protect.policy.check()`; read the decision log record |
| `MAIN-PROTECT-0002` | runtime | Time-locked: before `releaseAt`, or the release round isn't available yet (403, `retryAfter`) | Wait for the release time |
| `MAIN-PROTECT-0003` | runtime | The asset, the person's access, the link or the licence was revoked, or the asset was erased (403; 410 when erased) | Protect and share a new copy if access should continue |
| `MAIN-PROTECT-0004` | runtime | No such asset, version, link, delegation or approval in this tenant (404, same body either way) | Check the id and the current tenant |
| `MAIN-PROTECT-0005` | runtime | A person must approve first; the problem carries `approvalId` and `retryAfter` (403) | Approve with `protect.approvals.update()`, or pass `approvals` |
| `MAIN-PROTECT-0006` | runtime | The approver declined, or the approval timed out (403) | Ask again, or `extend` the approval before it times out |
| `MAIN-PROTECT-0007` | runtime | Delegation invalid: wider than the person, expired, revoked, used up or deeper than 3 (403) | Create a delegation within what the person may do |
| `MAIN-PROTECT-0008` | runtime | A query or play budget, or a delegation's `maxUses`, is used up (429) | Wait for the budget to reset, or raise it in the policy |
| `MAIN-PROTECT-0009` | runtime | A session, print, device or recipient-verification rate limit was passed (429, `retryAfter`) | Retry after `retryAfter` |
| `MAIN-PROTECT-0010` | runtime | Suite not supported: `TAPS-CS3` is refused until it is registered; no post-quantum protection is claimed (400) | Use `TAPS-CS1` or `TAPS-CS2` |
| `MAIN-PROTECT-0011` | runtime | Threshold release not reached: fewer than `t` parties have released (403, retryable) | Wait for more parties; see `protect.threshold.get()` |
| `MAIN-PROTECT-0012` | runtime | The asset or its label is locked down, suspended or quarantined (423) | Lift the lockdown with approvals, or replace a quarantined file |
| `MAIN-PROTECT-0013` | runtime | Step-up required: the policy needs a fresher or stronger sign-in, listed in `requirements` (401) | Sign in again with the listed method |
| `MAIN-PROTECT-0014` | runtime | The TAPS Node, a threshold party or the sealing service is unreachable (503, retryable); nothing opens without a licence | Check `protect.url` and the network; retry |
| `MAIN-PROTECT-0015` | runtime | Invalid input: unknown policy key, label `pan`, a zone id that isn't opaque, `t` outside 2 to n, `releaseAt` in the past, an unknown party or an undeclared agent (400) | Fix the call; `protect.policy.lint()` names policy issues |
| `MAIN-PROTECT-0016` | runtime | The file's version is superseded; `location` names the current version (409) | Open the current version |
| `MAIN-PROTECT-0017` | runtime | The ledger is stale or the registration is pending (503, `retryAfter`) | Retry after `retryAfter` |
| `MAIN-PROTECT-0018` | runtime | A query answer was refused by the output controls: the whole document, a verbatim span over the limit, or a denied field (422) | Ask a narrower question |
| `MAIN-PROTECT-0019` | runtime | The driver's profile lacks the capability the call needs, such as `query` or `web3` (501) | Use a driver whose profile has it |
| `MAIN-PROTECT-0020` | check | A `@taps/*` package is imported outside `@mainsdk/protect-taps` | Call `protect` instead |
| `MAIN-PROTECT-0021` | check | The `protect` section is invalid: unknown key or driver, no `url` or `share-domain` for a `taps-*` driver, no `key`, `suite: TAPS-CS3`, `renew` outside 5s to 5m, or a threshold party without a URL | Fix the section the finding names |
| `MAIN-PROTECT-0022` | check | A production build resolves `@taps/*` from a folder (`link:` or `file:`) instead of the registry | Install `@taps/*` from npm once published; until then don't ship `@mainsdk/protect-taps` to prod |

## LICENCE

Codes from app licensing (spec `licence`, built, and spec `licence-cloud`, planned for 0.6). The check reports 0011, 0012 and 0014; the rest are raised at runtime. Not TAPS licences: those are `MAIN-PROTECT`. Runtime codes are also listed in [errors](https://mainsdk.dev/docs/reference/errors).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-LICENCE-0001` | runtime | The feature needs a licence and the licence in scope doesn't include it, or isn't valid or in grace (403, with `licence: { feature, status, reason }`) | Run `mainsdk licence show`; install a licence that includes the feature with `licence.update()` |
| `MAIN-LICENCE-0002` | runtime | A licensed limit is reached: the licence's ceiling is the one that binds (403, with `licence: { name, limit }`) | Ask the vendor for a licence with a higher limit, or set `licence.over: report` |
| `MAIN-LICENCE-0003` | runtime | A licensed limit was passed with `over: report`; the call was allowed. Logged once per limit and scope per UTC day | Renew the licence with a higher limit before the true-up |
| `MAIN-LICENCE-0004` | runtime | A licence, CA certificate or revocation list doesn't verify; `reason` is `signature`, `chain`, `format`, `subject`, `binding`, `rollback` or `test-root` (400 from `licence.update()`) | Ask the issuer for a new file; check `licence.roots`, `licence.product`, `project` and the environment |
| `MAIN-LICENCE-0005` | runtime | The licence is in grace: expiring, revoked or suspended. Warned once a day with `graceEndsAt` | Renew the licence, or let refresh fetch the renewed one |
| `MAIN-LICENCE-0006` | runtime | The licence is expired, revoked or suspended past its grace; licensed features are off | Install a renewed licence; the rest of the app keeps serving |
| `MAIN-LICENCE-0007` | runtime | No licence, or not yet valid; licensed features are off | Set `licence.file` or `licence.token`, or install one with `licence.update()` |
| `MAIN-LICENCE-0008` | runtime | Refresh failed, or the newest revocation list is past its `nextUpdate`; the current state is kept. Logged once per outage | Check `licence.url` and the network; nothing is blocked meanwhile |
| `MAIN-LICENCE-0009` | runtime | An older licence (`seq`) or revocation list (`number`), or a different list with the same number, was refused; the newer one stays | Install the newest licence; report repeated attempts as a security event |
| `MAIN-LICENCE-0010` | runtime | The clock is behind the high-water time by more than `licence.skew`; the high-water time is used for licence decisions | Fix the machine's clock (NTP) |
| `MAIN-LICENCE-0011` | check, runtime | The `licence` section is invalid: unknown driver or key, no `product`, no `roots` or more than 4, a root that isn't `ed25519:` and 32 bytes, both `file` and `token`, `http` without `url`, `refresh` outside 5m to 7d, `skew` outside 0 to 1h. The app doesn't start | Fix the key the finding names |
| `MAIN-LICENCE-0012` | check | A feature name passed to `licence.has` or `licence.require` isn't under `licence.features` | Add the name to `licence.features`, or fix the typo |
| `MAIN-LICENCE-0013` | runtime | A feature name that isn't under `licence.features`: `has` returns false and logs once; `require` throws (500) | Add the name to `licence.features`, or fix the typo |
| `MAIN-LICENCE-0014` | check | The test root is pinned under `licence.roots` in production | Pin your own root from MainSDK Cloud or your issuer |
| `MAIN-LICENCE-0015` | runtime | The machine id can't be read: no `/etc/machine-id` for `machine: os`, or `MAINSDK_MACHINE_ID` unset for `machine: env` (500) | Set `licence.machine: env` and `MAINSDK_MACHINE_ID`, or use a licence with no machine binding |
| `MAIN-LICENCE-0016` | runtime | `licence.update` refused: no `licence.manage` permission, an app licence outside `tenant.system()` in a tenanted app, or a tenant licence for another tenant (403) | Grant `licence.manage`, or install the licence in its own tenant |
| `MAIN-LICENCE-0020` | runtime | Cloud: the caller lacks the role, or a write has no passkey session from the last 5 minutes (403) | Sign in again with a passkey; ask an owner for `licences:admin` |
| `MAIN-LICENCE-0021` | runtime | Cloud: the licence claims are invalid; `errors` names each field (422) | Fix the fields; see spec `licence-cloud` for the issuing rules |
| `MAIN-LICENCE-0022` | runtime | Cloud: no such root, CA or licence in this account (404) | Check the id and the account |
| `MAIN-LICENCE-0023` | runtime | Cloud: the change conflicts with the state, such as renewing a revoked licence or issuing from a retired CA (409) | Read the resource's status; issue a new licence or use the active CA |
| `MAIN-LICENCE-0024` | runtime | Cloud: a second approver is needed; the problem carries `approvalId` | Ask another admin to approve |
| `MAIN-LICENCE-0025` | runtime | Cloud: more than 60 refresh calls for one licence in an hour (429, `Retry-After`) | Wait for `Retry-After`; keep `licence.refresh` at 5m or more |
| `MAIN-LICENCE-0026` | runtime | Cloud: the key service can't sign; nothing was issued or changed (503, retryable) | Retry; apps keep verifying offline meanwhile |

## Modern AI: multimodal, images, video, agent loop, routing and local models

Specs `ai-multimodal`, `ai-image`, `ai-run` and `ai-routing` (planned for 0.4), `ai-local` (planned for 0.5) and `ai-video` (planned for 0.6).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-AI-0040` | runtime | A prompt part is invalid: unknown type, no file, a `mime` that doesn't match the bytes, `pages` out of order, or `video` given as bytes (400); nothing is sent | Pass a `FileRef` of a supported type, and let MainSDK read the type |
| `MAIN-AI-0041` | runtime | A prompt part is over a limit: size, pixels, pages, duration, frames or `max-parts` (413); nothing is sent | Send a smaller file or fewer parts, or raise `ai.input` on purpose |
| `MAIN-AI-0042` | runtime | The model or driver doesn't accept this kind of part (501) | Use a model whose driver declares the modality |
| `MAIN-AI-0043` | runtime | A labelled image, audio or scan would go to a driver whose data use or region doesn't meet the rules, and media can't be redacted (403) | Use a driver that meets `ai.data` with an endpoint in the tenant's region |
| `MAIN-AI-0044` | check | A prompt part is built from request body bytes or a `data:` URL instead of a `FileRef` | Upload through `files` and pass the `FileRef` |
| `MAIN-AI-0045` | runtime | An image option is invalid: size, count, mask size or an empty prompt (400); nothing is sent | Pass a size from `ai.image.sizes`, a count within `max-count` and a mask the image's size |
| `MAIN-AI-0046` | runtime | The image driver doesn't offer this operation (501) | Use a driver that declares edit, inpaint or variations |
| `MAIN-AI-0047` | runtime | The provider refused the image prompt under its content policy (422) | Change the prompt; the reason code is in the audit event |
| `MAIN-AI-0048` | runtime | A content credential couldn't be signed and `ai.credentials.required` is true (500) | Restore the signer key in `keys`, or check its certificate |
| `MAIN-AI-0049` | check | AI images are generated with no `ai.credentials.signer` (warning) | Set a signer so images carry C2PA content credentials |
| `MAIN-AI-0050` | runtime | A video option is invalid: seconds, size, prompt or references (400); nothing is sent | Pass values within `ai.video` and the driver's limits |
| `MAIN-AI-0051` | runtime | No video job with that id in the current tenant (404) | Use a job id returned in this tenant |
| `MAIN-AI-0052` | runtime | The provider failed or refused the video job; the job is `failed` | Read the reason code; change the prompt or retry later |
| `MAIN-AI-0053` | runtime | A video job lost its provider heartbeat and was cancelled at the provider | Retry the job; check the provider's status |
| `MAIN-AI-0060` | runtime | An `ai.run` option is invalid: goal and messages, `maxSteps`, budget, timeout or agent (400); nothing is sent | Pass one of `goal` or `messages`, a declared agent and limits within range |
| `MAIN-AI-0061` | runtime | The run stopped at `maxSteps` (`stop: "max-steps"`) | Raise `maxSteps` on purpose, or narrow the goal or tools |
| `MAIN-AI-0062` | runtime | The run stopped at its budget (`stop: "budget"`) | Raise the run's budget within the agent's, or use a cheaper model |
| `MAIN-AI-0063` | runtime | The run stopped at its timeout (`stop: "timeout"`) | Raise `timeout`, or use `durable: true` for long runs |
| `MAIN-AI-0064` | runtime | The model asked for a tool that isn't in the run's `tools`; the step was refused | Nothing, if the tool shouldn't be reachable; otherwise add its action to `tools` |
| `MAIN-AI-0065` | runtime | A handoff or delegation names an agent not declared for it (400) | Add the agent under `agents.<name>.run.handoff` or `delegate` |
| `MAIN-AI-0066` | runtime | A delegation asked for more than the parent's remaining budget or the declared share (402) | Delegate less, or raise the declared share on purpose |
| `MAIN-AI-0067` | runtime | No run with that id in the current tenant, or it isn't waiting (404 or 409) | Use a run id from this tenant that is waiting |
| `MAIN-AI-0068` | check | A tool passed to `ai.run` isn't `ai.tool()` of a declared action | Declare the tool with `action()` and pass `ai.tool(action)` |
| `MAIN-AI-0070` | check | A route lists a model not in `ai.models`, unpriced, or whose driver doesn't meet `ai.data` | Remove the model from the route, or fix its allowlist, price or driver |
| `MAIN-AI-0071` | runtime | Every model in the route failed with a retryable error (502) | Check the providers' status; add another model that meets the rules |
| `MAIN-AI-0072` | runtime | A fallback model was skipped because its endpoint is outside the tenant's region for labelled data (logged) | Add a model with an endpoint in that region to the route |
| `MAIN-AI-0073` | runtime, check | A response cache entry is invalid: tenant scope with labelled data, a TTL over 7 days, or `local` kv in production | Use `scope: user`, a shorter TTL, or a production kv driver |
| `MAIN-AI-0074` | runtime | A batch option is invalid: no items, too many, duplicate ids, or no batch API (400) | Fix the items, or use a driver with a batch API |
| `MAIN-AI-0075` | runtime | No batch with that id in the current tenant (404) | Use a batch id returned in this tenant |
| `MAIN-AI-0076` | runtime | The store that counts `ai.limits` did not answer and the call is under a spend limit, so it is refused (503, retryable) | Check `runtime.store`; calls under no limit keep running |
| `MAIN-AI-0078` | runtime | The local model server is unreachable (503, retryable) | Start it, for example `ollama serve` |
| `MAIN-AI-0079` | check | A local endpoint uses plain HTTP off the machine, isn't in `network.allow`, or a remote one lacks `data` or `region` | Use HTTPS, allow the host, and declare its data use and region |
| `MAIN-AI-0080` | runtime | The model isn't on the local server (404) | Fetch it, for example `ollama pull llama3.2:3b` |

## DOC

Documents (spec `documents`, planned for 0.4).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-DOC-0001` | runtime | The file isn't a supported document type, or its bytes don't match its declared type (415) | Send a PDF, DOCX, XLSX, PPTX, PNG, JPEG or TIFF |
| `MAIN-DOC-0002` | runtime | Over a limit: size, pages, ZIP expansion, or more pages than `inline-pages` for `parse` (413) | Use `documents.start` for large files, or raise `documents.limits` on purpose |
| `MAIN-DOC-0003` | runtime | Pages have no text layer and OCR is off or no OCR driver is set (422) | Set `documents.ocr.driver`, or pass `ocr: "auto"` |
| `MAIN-DOC-0004` | runtime | The documents driver doesn't offer this (501) | Use a driver that declares the capability |
| `MAIN-DOC-0005` | runtime | The PDF is encrypted or password protected (422) | Ask for an unprotected copy |
| `MAIN-DOC-0006` | runtime | Active content was found and not run (logged) | Nothing to do; review `findings` if the file is suspicious |
| `MAIN-DOC-0007` | runtime | A render layout or template is invalid (400) | Fix the element, template name, font or value the error names |
| `MAIN-DOC-0008` | runtime | A labelled document would go to a driver outside the tenant's region or not meeting the data rules (403) | Add an endpoint for the region, or use a driver that meets `ai.data` |
| `MAIN-DOC-0009` | runtime | No document job with that id in the current tenant (404) | Use a job id returned in this tenant |
| `MAIN-DOC-0010` | check | A PDF or Office library used outside a driver | Call `documents` instead |
| `MAIN-DOC-0011` | check | A locale with a complex script renders with the `builtin` renderer, which doesn't shape it | Use the `gotenberg` or `docraptor` render driver |

## SANDBOX

Running untrusted code (spec `sandbox`, planned for 0.4).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-SANDBOX-0001` | runtime | A sandbox option is invalid (400); nothing ran | Fix the language, code, limit or path the error names |
| `MAIN-SANDBOX-0002` | runtime | The code reached its time limit and was killed | Raise `timeout` within `sandbox.limits`, or make the code faster |
| `MAIN-SANDBOX-0003` | runtime | The code passed its memory limit and was killed | Raise `memory` within `sandbox.limits` |
| `MAIN-SANDBOX-0004` | runtime | Output or files passed their limit; output is cut | Write less, or raise `limits.output` on purpose |
| `MAIN-SANDBOX-0005` | runtime | A host isn't in `sandbox.network` and `network.allow`, or the code tried a host it wasn't given (403) | Add the host to both lists on purpose |
| `MAIN-SANDBOX-0006` | runtime | The sandbox driver is unavailable (503, retryable) | Retry; check the provider's status |
| `MAIN-SANDBOX-0007` | runtime | The run would pass, or reached, its cost ceiling (402) | Lower `timeout`, or raise `maxCost` on purpose |
| `MAIN-SANDBOX-0008` | runtime | No sandbox session with that id in the current tenant, or it was closed (404) | Create a new session |
| `MAIN-SANDBOX-0009` | runtime | A secret reference isn't under `sandbox.secrets` (403) | List the secret under `sandbox.secrets` on purpose |
| `MAIN-SANDBOX-0010` | check | `eval`, `new Function` or `node:vm` runs a value that isn't a string literal | Run the code with `sandbox.run` |
| `MAIN-SANDBOX-0011` | check, runtime | The `local` sandbox driver in production | Use `vercel-sandbox` or `e2b` in production |
| `MAIN-SANDBOX-0012` | check | `sandbox.network` lists a host that `network.allow` doesn't | Add the host to `network.allow`, or remove it from `sandbox.network` |

## I18N

Languages and formats (spec `i18n`, planned for 0.4).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-I18N-0001` | check | A key is missing from a required locale | Add the message, or run `mainsdk i18n draft` and approve it |
| `MAIN-I18N-0002` | check | A locale isn't supported by the target runtime's `Intl` | Use a runtime with full ICU, or drop the locale |
| `MAIN-I18N-0003` | check | A message has a syntax error, or its variables differ from the default locale's | Fix the message so it parses and uses the same variables |
| `MAIN-I18N-0004` | runtime | A message was missing and a fallback was used (logged once per key and locale) | Add the message in that locale |
| `MAIN-I18N-0005` | runtime | `t()` was called without a value its message needs (logged) | Pass every variable the message uses |
| `MAIN-I18N-0006` | check | `review: none`: AI drafts reach users without review (warning) | Set `review: person` unless you accept the risk on purpose |
| `MAIN-I18N-0007` | runtime | An agent or service tried to approve a translation draft (403) | A person approves drafts |
| `MAIN-I18N-0008` | check | `i18n.negotiate` lists `ip` or an unknown source | Use `choice`, `account` and `header` |
| `MAIN-I18N-0009` | runtime | No message for the key in any locale; production never shows the key (logged) | Add the message to the default locale |

## VOICE

Realtime voice agents (spec `ai-voice`, planned for 0.6).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-VOICE-0001` | runtime | A voice session option is invalid (400) | Pass one of `model` or `pipeline`, a known voice and a declared agent |
| `MAIN-VOICE-0002` | runtime | The voice driver doesn't offer this (501) | Use a driver that declares the capability |
| `MAIN-VOICE-0003` | runtime | Recording refused: recording off, or no consent from the caller (403) | Set `record: consent` and record the caller's consent first |
| `MAIN-VOICE-0004` | runtime | The session reached its duration or cost limit and ended after a closing line | Raise `maxDuration` or the limit on purpose |
| `MAIN-VOICE-0005` | runtime | A telephony or room webhook failed signature verification (401) | Check the webhook secret; investigate the sender |
| `MAIN-VOICE-0010` | check | A phone number routes to a voice session with no disclosure | Set `ai.voice.disclosure` or the session's `disclosure` |
| `MAIN-VOICE-0011` | check | A voice, telephony or room driver's hosts aren't in `network.allow` | Allow the hosts on purpose |

## EVAL

Evals for AI features (spec `ai-evals`, planned for 0.5).

| Code | Raised by | Meaning | Fix |
| --- | --- | --- | --- |
| `MAIN-EVAL-0001` | CLI | An eval set is invalid, or its judge model is the feature's own model (exit 2) | Fix the set as the error names; pick a different judge model |
| `MAIN-EVAL-0002` | CLI, check | A feature's score is below its threshold or regressed from the baseline (exit 1) | Fix the prompt or model, or update the baseline on purpose |
| `MAIN-EVAL-0003` | check | A prompt or model changed since the last eval result, or a feature with an eval set has none | Run `mainsdk eval` |
| `MAIN-EVAL-0004` | check | An eval set or exported sample holds personal data | Replace the value with a synthetic one |
| `MAIN-EVAL-0005` | CLI | The eval run would pass `--max-cost` (exit 2) | Raise `--max-cost` on purpose, or run one feature |

## Codes from other specs

These check, CLI or mixed codes are defined in a spec's Codes table and listed here automatically. The spec holds the full cause, and `npx mainsdk explain <code>` gives the fix.

<!-- codes:begin (generated by tools/build_codes.py; edit the spec's Codes table, never these rows) -->
| Code | Raised by | Meaning | Spec |
| --- | --- | --- | --- |
| `MAIN-ADOPT-0002` | CLI | The stack is not Next.js or Node; `adopt` stops and changes nothing | `migration-skill` |
| `MAIN-ADOPT-0003` | CLI | A route changes or reads data and never checks who is calling (access gap) | `migration-skill` |
| `MAIN-ADOPT-0004` | CLI | The browser queries the database directly, so row rules are the only protection (data gap) | `migration-skill` |
| `MAIN-ADOPT-0006` | CLI | There is nothing to migrate in the module, or it is not a module (`secrets`, `auth`, `data`, `other`) | `migration-skill` |
| `MAIN-ADOPT-0007` | CLI | A call still sits behind an interface's `raw()` escape hatch; listed by `finish` with file and line | `migration-skill` |
| `MAIN-ADOPT-0008` | CLI | The working tree has uncommitted changes; a module step starts from a clean tree | `migration-skill` |
| `MAIN-ADOPT-0009` | CLI | No sign-in or checkout flow was found to lock, or a named flow points at text that is not there | `migration-skill` |
| `MAIN-ADOPT-0010` | CLI | A module step is still open, or `verify` ran with none open | `migration-skill` |
| `MAIN-ADOPT-0012` | CLI | The folder is not a git repository, or the module branch could not be created | `migration-skill` |
| `MAIN-ADOPT-0013` | CLI, MCP | The name is not an adopt tool, or not an agent adopt writes a skill for | `migration-skill` |
| `MAIN-ADVISOR-0001` | check | `advisor` is invalid: `may` empty or naming an undeclared rule, `run: auto` with a rule in `may` that has an `app` or `people` step, an unknown wake signal, or no `agents.advisor` | `advisor` |
| `MAIN-API-0020` | check | CORS lets any origin call the API (`*`, `origin: true` or a bare `cors()`) | `main27-baseline` |
| `MAIN-ASSURE-0001` | check, CLI | An exception in `main.yaml` for a `<standard>:<control>` rule has no reason, approver or expiry (400). Fix: give every exception a reason, an approver and an expiry date | `assure` |
| `MAIN-ASSURE-0002` | CLI | No standard, pack, format or run file by that name, or no standard was chosen (400). Fix: use one of the standards the message lists | `assure` |
| `MAIN-ASSURE-0004` | CLI | An evidence bundle does not verify: the signature fails, a section is missing or no public key was given (exit 1). Fix: do not rely on the bundle; run assure again on the repo | `assure` |
| `MAIN-ASSURE-0005` | CLI | No mainsdk record could be read from the URL (exit 2). Fix: check the address serves `/.well-known/mainsdk.json` over HTTPS | `assure` |
| `MAIN-ASSURE-0006` | cloud | Assigning a failure to a teammate from the console needs Teams (402, with an `upgrade` link). Fix: upgrade to Teams, or assign the failure in your own tracker | `assure` |
| `MAIN-ASSURE-0007` | cloud | The failure to assign is not in the account's latest run (404). Fix: assign a ref from the latest run | `assure` |
| `MAIN-ASSURE-0008` | CLI | `--fix` could not open its pull request: git has no origin, `gh` is not signed in, or the tree is not clean (502). Fix: fix the git setup, or apply the listed changes by hand | `assure` |
| `MAIN-AUTH-0012` | check, runtime | Check (high): an admin role in `auth.admin.roles` can sign in with a method phishing can defeat while `auth.admin.require` isn't `phishing-resistant`. Runtime: `auth.raw()` was called (logged). Fix: set `auth.admin.require: phishing-resistant`, or remove the weak methods from `auth.methods` | `auth` |
| `MAIN-AUTH-0053` | check | `auth.risk.step-up` names a method that isn't on, or only methods weaker than the ones it steps up from | `auth` |
| `MAIN-AUTH-0055` | check | The identity-provider driver named by `auth.driver` does not offer a method (its capability profile says `false`). High, and it fails the check, when the app uses the method; a warning otherwise | `auth` |
| `MAIN-AUTH-0081` | client | The person cancelled the passkey prompt, or the browser refused it (`NotAllowedError` or `AbortError`); not retryable without a new gesture | `auth-client` |
| `MAIN-AUTH-0082` | client | The auth routes answered 404 or HTML: the adapter isn't mounted or `base` is wrong | `auth-client` |
| `MAIN-AUTH-0083` | client | This browser has no WebAuthn, or no conditional mediation when `mediation: "conditional"` was asked for | `auth-client` |
| `MAIN-AUTH-0090` | check | A password is stored with a bare hash instead of passkeys or the auth interface | `main27-baseline` |
| `MAIN-AUTH-0091` | check | The sign-in uses the OAuth implicit flow (`response_type=token`) | `main27-baseline` |
| `MAIN-AUTH-0101` | check | `assetlinks.json` or `apple-app-site-association` does not match the signing identity declared in `targets.mobile.signing`, so app links and passkeys would not bind to the app | `mobile-auth` |
| `MAIN-BACKUP-0001` | check | The provider's best RPO (PITR step, else snapshot gap) is above `backup.rpo`. Fix: turn on PITR or raise `backup.rpo` | `backup-restore-evidence` |
| `MAIN-BACKUP-0002` | check | The provider keeps restore points for less than `backup.keep`. Fix: raise the provider retention or lower `backup.keep` | `backup-restore-evidence` |
| `MAIN-BACKUP-0003` | check | The last drill took longer than `backup.rto`. Fix: shrink the restore path or raise `backup.rto` to what a drill measured | `backup-restore-evidence` |
| `MAIN-BACKUP-0006` | check | `backup.rpo`, `backup.rto`, `backup.keep` or `backup.drill` is missing or not a duration. Fix: set durations such as `15m`, `1h`, `35d` | `backup-restore-evidence` |
| `MAIN-BASE-0001` | pack build | A point update removes a rule an earlier point had; point updates only add checks | `main27-baseline` |
| `MAIN-BASE-0002` | contract check | An interface outside the phase 1 stable core is marked `stable` without two drivers, a passing conformance suite and three production users | `main27-baseline` |
| `MAIN-BOT-0005` | check | A `bots` value is invalid: a door path that matches no route, `challenge` not below `deny`, an unknown country code or CIDR, or an unknown key | `bot-defence` |
| `MAIN-CACHE-0011` | check | `cache.scope: public` on an action whose `risk` isn't `read`, whose method isn't `GET`, or that declares a `permission` | `http-cache` |
| `MAIN-CACHE-0012` | check | An app-scoped `cache.wrap` or `cache.set` holds the result of a `db` read, which is owner or tenant data | `http-cache` |
| `MAIN-CANARY-0003` | check | `canaries` is set but nothing is planted in that env, or a model named under `records` doesn't exist | `exfiltration-guard` |
| `MAIN-CONFIG-0030` | check | A `main.yaml` key isn't in the schema; `fix` names the nearest key, so `maxSize` suggests `max-size` and `payments` suggests `pay` | `cohesion` |
| `MAIN-CONFIG-0031` | check | A store-backed feature that must survive a restart (idempotency, meter, workflow leases) runs on a store whose profile says `durable: false` | `cohesion` |
| `MAIN-CONFIG-0032` | check | A `main.yaml` value fails the schema: wrong type, not the one allowed constant, or not matching the key's pattern; the finding names the path. Fix: write the value in the form the finding shows | `cohesion` |
| `MAIN-CONFIG-0033` | check | The `main.yaml` schema isn't built, so keys and values weren't validated (low, a warning). Fix: run `pnpm build` in `packages/sdk`, which runs `tools/build_main_schema.py` | `cohesion` |
| `MAIN-CONNECTOR-0001` | check, runtime | A connector's settings are not usable: an unknown driver, a missing https `instance` or `url`, or `auth` that is not a `secret:NAME` reference | `connectors` |
| `MAIN-CONTEXT-0001` | check | `context` is invalid: no `group`, a purpose without a description, a field outside the built-in schema or the app's declared extras, `retention` over 90d, a `share-with` app that isn't a mutual peer, or a sink other than `db` or `events` | `context` |
| `MAIN-CONTEXT-0006` | check | Shared context in an app with `users.audience: children`, or a purpose touching a children's audience, without the purpose marked `children: guardian-consent` and spec privacy-lifecycle's age gate in place | `context` |
| `MAIN-CONTRACT-0001` | build | Two error registry entries share a code, or a code does not match `MAIN-<AREA>-<NNNN>`; the message names both entries | `errors` |
| `MAIN-CONTRACT-0004` | CLI | `contract diff --base` found no contract snapshot at the given ref or file | `versioned-contracts` |
| `MAIN-CRYPTO-0013` | check | `crypto.fips` is on but `crypto.module` does not name the validated module, its version and certificate number | `post-quantum` |
| `MAIN-DATA-0040` | check | A statement takes a lock that blocks reads or writes on an existing table while it runs | `db-migrations` |
| `MAIN-DATA-0041` | check | A rename or drop of a column or table that the base ref's code still reads, so the running release breaks during the deploy | `db-migrations` |
| `MAIN-DATA-0042` | check | A new migration for a tool that can't take a lock timeout from the runner doesn't set `lock_timeout` itself | `db-migrations` |
| `MAIN-DATA-0043` | check | An `UPDATE` or `DELETE` with no `WHERE`, or a backfill of a whole table, in a migration; run it as a batched job | `db-migrations` |
| `MAIN-DATA-0044` | CLI | A migration statement timed out waiting for a lock after every retry; nothing after it was applied | `db-migrations` |
| `MAIN-DATA-0045` | CLI | Another instance holds the migration lock; this run waited and found every migration already applied | `db-migrations` |
| `MAIN-DATA-0051` | check | A serverless target connects to Postgres without a pooled endpoint, so each instance opens its own connections | `db-queries` |
| `MAIN-DATA-0055` | check | A `db` call is awaited inside a loop over the results of another query | `db-queries` |
| `MAIN-DATA-0056` | check | A `db.timeout`, `db.pool` or `db.slow` value is invalid: a request timeout over 30s, a pool `max` over 100, or `slow` not under the request timeout | `db-queries` |
| `MAIN-DATA-0061` | check | `jobs.run`, `events.publish`, `webhooks.emit`, `email.send` or `notify` called inside a `db.transaction` callback on the module instead of on `tx` | `db-writes` |
| `MAIN-DATA-0062` | check | A unique index on a model with trash doesn't exclude trashed rows, so a deleted record blocks a new one | `db-writes` |
| `MAIN-DATA-0065` | check | `trash` on a model with a labelled field is longer than that label's retention, or `trash` isn't a valid duration | `db-writes` |
| `MAIN-DATA-0070` | check | SQL is built from strings (a template literal or concatenation) | `main27-baseline` |
| `MAIN-DATA-0071` | check | A connection string uses a shared admin account such as `root`, `admin` or `postgres` | `main27-baseline` |
| `MAIN-DATA-0180` | check | A query filters, sorts or joins on the raw value of a vaulted field, which the database holds only as a token. Fix: use the driver's blind index, or look the person up by an id | `residency-vaults` |
| `MAIN-DATA-0181` | check | The vault driver's declared countries (`vault.countries`) miss a country in `markets`. Fix: pick a driver that supports it or drop the market | `residency-vaults` |
| `MAIN-DATA-0182` | check | A vaulted field has a label a vault cannot hold, such as `pan`. Fix: use a canonical label; never store card numbers | `residency-vaults` |
| `MAIN-DEBUG-0001` | cloud | A debug session, replay, hosted triage or inbox forwarding needs Teams (402, with an `upgrade` link). The app is not changed. Fix: move the project to Teams | `debug-loop` |
| `MAIN-DEBUG-0002` | cloud | A debug session must name exactly one of user, request or release, and a duration such as `30m` or `1h` (422). Fix: give one target and a valid `--for` | `debug-loop` |
| `MAIN-DEBUG-0003` | cloud | No debug session has that id in this project (404). Fix: list the sessions of the project and pass one of their ids | `debug-loop` |
| `MAIN-DEBUG-0004` | cloud, CLI | The trace has no recorded request, or the project has no replay handler for its action (404). Fix: check the trace id, or export the action from `mainsdk.replay.ts` | `debug-loop` |
| `MAIN-DEBUG-0005` | cloud | Triage needs the GitHub app connected for this project (409). Fix: run `mainsdk triage connect github` | `debug-loop` |
| `MAIN-DEBUG-0006` | cloud | Triage has not opened that issue or pull request (404). Fix: run `mainsdk triage run` first, then pass the number it printed | `debug-loop` |
| `MAIN-DEBUG-0007` | cloud | A report, repository or screenshot address is not valid; screenshots must be getqr.id uploads (422). Fix: upload the screenshot through getqr.id and send its link | `debug-loop` |
| `MAIN-DEPLOY-0001` | check, CLI | A schedule can't be deployed: its expression is computed at runtime and the target has no long-running process, or `jobs.schedules` and a `jobs.schedule` call give one name two expressions | `deploy` |
| `MAIN-DEPLOY-0002` | check, CLI | `deploy.regions` names a region outside the app's data regions, or the target can't run in a data region | `deploy` |
| `MAIN-DEPLOY-0003` | CLI | `deploy preflight` found required env var names missing or empty in the build; the names are listed, never a value | `deploy` |
| `MAIN-DEPLOY-0004` | check, CLI | A schedule or region breaks the declared platform plan's limit (for example a cron more often than daily on Vercel Hobby, or two regions on Hobby) | `deploy` |
| `MAIN-DEPLOY-0005` | check, CLI | A Next.js app targets Docker or Fly without `output: "standalone"` in its Next.js config | `deploy` |
| `MAIN-DEPLOY-0010` | check, CLI | A generated block is stale against `main.yaml`, or was edited by hand; the fix is the `deploy config` command that rewrites it | `deploy` |
| `MAIN-DEPLOY-0011` | check, CLI | A secret would reach the image or the build log: a Dockerfile `ARG` or `ENV` named after a `secret:` reference, or `.dockerignore` not excluding `.env*` | `deploy` |
| `MAIN-DEPLOY-0012` | CLI | `deploy diff --fail-on widen` found a change that widens what the target environment may do: a new allowed host, a new secret, a new region or a looser grant | `deploy` |
| `MAIN-DEPS-0001` | check | A direct dependency isn't on its registry: possibly a name a model made up, and anyone may register it (high) | `dependency-check` |
| `MAIN-DEPS-0002` | check | A direct dependency's first version is younger than `deps.min-age` (high) | `dependency-check` |
| `MAIN-DEPS-0003` | check | A direct dependency's name is one edit away from a popular package it isn't (medium) | `dependency-check` |
| `MAIN-DEPS-0004` | check | A resolved package has a known advisory; at or above `advisories.fail-on` it fails, below it warns | `dependency-check` |
| `MAIN-DEPS-0005` | check | A package's licence is denied, outside a non-empty allow list, or unknown with `unknown: fail` | `dependency-check` |
| `MAIN-DEPS-0006` | check | A package runs an install script (`preinstall`, `install`, `postinstall`) and isn't in `deps.scripts.allow` (warning) | `dependency-check` |
| `MAIN-DEPS-0007` | check | Advisories and package ages weren't checked because the network was unavailable (info, or a failure with `offline: fail`) | `dependency-check` |
| `MAIN-DEPS-0008` | check | An advisory ignore entry has expired, or has no `until` or `reason` | `dependency-check` |
| `MAIN-DEV-0001` | cli | A fix, recipe or MCP write would widen a grant (`network.allow`, `permissions`, `access` roles, `agents` budgets, an exception); it is planned but not applied without `--allow-widen` from a person, and `next` returns `ask-person` | `agent-experience` |
| `MAIN-DEV-0002` | cli | A recipe or fix doesn't apply cleanly to the current code; `fix` names the file and the first conflicting hunk | `agent-experience` |
| `MAIN-DEV-0003` | cli | An MCP write tool was called on a server started without `--allow-write` | `agent-experience` |
| `MAIN-DEV-0004` | check | The generated types are older than `main.yaml`; run `mainsdk dev`, `sync` or `next` | `agent-experience` |
| `MAIN-DEV-0005` | cli | An unknown command, subcommand, flag or preset; `fix` names the nearest match and `mainsdk help` (exit 2) | `design-language` |
| `MAIN-DEV-0006` | cli | `init` found an existing `main.yaml`; `fix` names `--new-id` and `--force` (exit 2) | `design-language` |
| `MAIN-DEV-0007` | cli | A command that reads `main.yaml` ran in a folder with none; `fix` names `mainsdk init` (exit 2) | `design-language` |
| `MAIN-DEV-0008` | cli | `mainsdk dev` refused to start under `env: prod`; `fix` names the dev environment (exit 2) | `design-language` |
| `MAIN-DEV-0009` | cli | `mainsdk dev <entry>` found no file at the entry, or no `fetch` function as its default export; `fix` names what to export (exit 2) | `design-language` |
| `MAIN-DEVICE-0001` | check | `mainsdk/device` is imported but `main.yaml` has no `device` section; device calls throw it at runtime (500) | `device-identity` |
| `MAIN-DEVICE-0002` | check | `main.yaml` declares `device` but no code imports `mainsdk/device`; nothing is served | `device-identity` |
| `MAIN-DEVICE-0003` | check, runtime | The `device` section is invalid: unknown driver or key, a value out of range, `authority` written as a literal instead of `secret:NAME`, more than 2 authority keys, an `oidc` entry without `issuer`, `audience` or `tenant`, or a proof not in the list. The app doesn't start | `device-identity` |
| `MAIN-DEVICE-0004` | check, runtime | `driver: taps` without `@mainsdk/device-taps` installed, or an `@taps/*` import outside that package | `device-identity` |
| `MAIN-DEVICE-0016` | check | Production runs with no `device.authority`, or with the development authority key that `mainsdk dev` generated | `device-identity` |
| `MAIN-DEVICE-0022` | check, runtime | The `device.attest` section is invalid: `require: hardware` or `environment`, `formats`, `roots`, `builds` or `min-security-level` with `driver: local`; an unknown format; a root or builds file that doesn't exist; `every` or `grace` out of range | `device-attest` |
| `MAIN-DEVICE-0038` | check, runtime | The `device.telemetry` section is invalid: a stream name that doesn't match the pattern, a size or rate out of range, `redact` that isn't a list of paths | `device-telemetry` |
| `MAIN-DEVICE-0039` | check | `device.telemetry.on` names a stream that isn't declared, or a declared stream has no handler | `device-telemetry` |
| `MAIN-DEVICE-0050` | check, runtime | The `device.policy` section is invalid: stages that don't increase or don't end at 100%, `hold` outside 5m to 7d, `rollback-if` outside 1% to 50%, `approve` above 2, or an unknown `tighten` direction | `device-policy` |
| `MAIN-DEVICE-0066` | check | A `client.commands.handle` handler passes its input to a process or an evaluator (`system.run`, `child_process`, `eval`, `new Function`, `vm`, dynamic `import()`) | `device-commands` |
| `MAIN-DEVICE-0067` | check | A command type is unsafe to declare: its input schema has an unbounded string field named `command`, `cmd`, `script`, `code`, `shell`, `exec` or `args`; it uses the `mainsdk.` prefix; it is `destructive` with `approve: 0`; or it is `reaction: true` while `destructive`, or `write` without `undo` | `device-commands` |
| `MAIN-DEVICE-0071` | check, runtime | The `device.commands` section is invalid: a value out of range, or `ttl` over `max-ttl` | `device-commands` |
| `MAIN-DEVICE-0082` | check, runtime | The `device.heartbeat` section is invalid: `every` outside 15s to 1h, `late-after` outside 2 to 10, `silent-after` outside 3 to 100 or not above `late-after` | `device-health` |
| `MAIN-DEVICE-0092` | check, runtime | The `device.taps` section is invalid: a `did:web` without a key-history log, `TAPS-CS3`, an unknown delegation target, or a status `refresh` outside 5m to 24h | `device-taps` |
| `MAIN-DEVID-0001` | cloud, sdk | The account in a developer record is not a GitHub login (400). Fix: run `mainsdk login` again to sign in with GitHub | `verified-developers` |
| `MAIN-DEVID-0002` | cloud | The identity provider answered something this version does not understand (502). Fix: try the verification again later | `verified-developers` |
| `MAIN-DEVID-0003` | cloud | The organisation could not be verified because a check could not run (502). Fix: try the verification again later | `verified-developers` |
| `MAIN-DEVID-0004` | cloud | Certified partner is not yet available to buy (409). Fix: choose Trusted publisher, which is earned, or ask to be told when partners open | `verified-developers` |
| `MAIN-DEVID-0005` | cloud | The appeal has nothing to appeal or does not say what was fixed (409). Fix: file an appeal after a drop and say what you fixed | `verified-developers` |
| `MAIN-DOCS-0001` | CLI | `mainsdk docs` ran in an install with no bundled docs; a source checkout builds them with `build_docs.py --bundle` | `docs-versions` |
| `MAIN-DOCS-0002` | CLI | The installed version has no docs page with that name; the fix lists the closest pages | `docs-versions` |
| `MAIN-DRIVER-0001` | usage | A listing, claim, revocation feed or driver path is not valid (400). Fix: run `mainsdk driver publish` to build the listing from a conformance run | `driver-marketplace` |
| `MAIN-DRIVER-0002` | usage | The driver fails every contract version it claims, so there is nothing to list (422). Fix: fix the failing conformance tests with `mainsdk driver test`, then publish again | `driver-marketplace` |
| `MAIN-DRIVER-0006` | check | The app uses a driver the marketplace revoked; the warning names the driver and the advisory. The app keeps serving (fail static). Fix: move to another driver or a fixed release | `driver-marketplace` |
| `MAIN-DRIVER-0007` | usage | The driver is not listed (404). Fix: search with `mainsdk driver search <interface>` | `driver-marketplace` |
| `MAIN-E2E-0007` | check, runtime | The post-quantum hybrid suite was asked for before spec post-quantum is in place (501) | `e2e` |
| `MAIN-E2E-0008` | check | A field in `e2e.fields` is read by server-side search, moderation or analytics, which skip it; `e2e.accept` silences it | `e2e` |
| `MAIN-E2E-0009` | check, runtime | The driver is not for production: `local` in production, `mls` without `@mainsdk/e2e-mls`, or a driver whose `production` is false in production (500) | `e2e` |
| `MAIN-EJECT-0001` | eject | No recipe exists for the interface, or for the driver `main.yaml` names; the fix lists the drivers that have one | `eject` |
| `MAIN-EJECT-0002` | eject | No file imports the interface, so there is nothing to eject | `eject` |
| `MAIN-EMAIL-0006` | check, runtime | The `email` section of `main.yaml` is invalid, names no driver, or lacks a value a call needs, such as `email.unsubscribe-url` (400) | `email-notify` |
| `MAIN-EMAIL-0009` | check | Email tracks opens or clicks; reported as a warning | `email-notify` |
| `MAIN-EMAIL-0010` | check | A real email driver in production with no `email.webhook`, so bounces and complaints never reach the suppression list; reported as a warning | `email-notify` |
| `MAIN-EMAIL-0011` | check | The source calls `email.marketing` with no `unsubscribe` | `email-notify` |
| `MAIN-EXFIL-0006` | check | An `exfiltration` value is invalid: a receiver not in `network.allow` or any driver's hosts, an unknown label, a bulk limit below 1, or an unknown key | `exfiltration-guard` |
| `MAIN-FILES-0016` | check | The configured `files` driver cannot meet a guarantee, named by its id in the message (a warning, so the run still passes): `uploadthing` declares `upload-single-use` and `data-region` | `files-share` |
| `MAIN-FLEET-0006` | check, runtime | A build includes a package the fleet policy blocks (403). Fix: update or remove the package | `fleet-control` |
| `MAIN-GEO-0002` | check | `geo.of` is used in access code: in a file under a folder named `access`, `policy`, `policies` or `auth`, or its call, or a variable it was put in, sits in the arguments of `auth.require`, `access.check`, `access.decide` or `policy.decide` | `geo` |
| `MAIN-GEO-0005` | check, runtime | A `geo` key is wrong (runtime: 400): an unknown `driver` or `edge`, a provider driver with no `key: secret:NAME`, or `geo.of` used with no declared edge | `geo` |
| `MAIN-GO-0001` | check | golangci-lint reported an issue in a Go project (the finding names the linter, the file and the line). Fix: Fix the code the linter points at, as its message says; never add a `nolint` | `go-sdk` |
| `MAIN-GO-0002` | check | gosec reported a weakness in Go code. Fix: Fix the weakness gosec names; never add a `#nosec` | `go-sdk` |
| `MAIN-GO-0003` | check | govulncheck found a known vulnerability the program can reach through a function it calls (the finding names the OSV id, the module and the fixed version). Fix: Upgrade the module to the fixed version the finding names | `go-sdk` |
| `MAIN-GO-0004` | check | A Go check tool isn't installed, so its gate did not run (a warning, never a pass). Fix: Install it: `go install golang.org/x/vuln/cmd/govulncheck@latest`, and gosec and golangci-lint the same way | `go-sdk` |
| `MAIN-GUARD-0001` | check, runtime | A rule with a `people` step is `run: auto`; or a source asked for an auto run of one | `reaction-safety` |
| `MAIN-GUARD-0002` | check, runtime | A step is on the never-a-reaction list; refused from every source | `reaction-safety` |
| `MAIN-GUARD-0005` | check, runtime | An app-class step was triggered by one tenant's signals without `tenant-quorum` tenants and without approval; it was turned into an approval | `reaction-safety` |
| `MAIN-GUARD-0008` | check | A `guard` value is outside its range, or `min-prefix` is set wider than /16 or /48 | `reaction-safety` |
| `MAIN-IDENT-0001` | check, runtime | An identity request asks for a claim beyond what it needs, gives no purpose, or an age gate is not a whole age from 1 to 99 | `digital-ids` |
| `MAIN-IDENT-0005` | check, runtime | `digital-ids` in `main.yaml` is not valid: no wallet listed, an unknown wallet, or a request with no claims or no need | `digital-ids` |
| `MAIN-KEYS-0021` | check | `keys.pkcs11` is incomplete or its PIN is a literal (400). Fix: set `keys.pkcs11.pin` to `secret:HSM_PIN` and name the module and `keys.key` | `hsm-keys` |
| `MAIN-KEYS-0023` | check | A FIPS claim has no level or CMVP certificate, or is made on a driver that is not an HSM (400). Fix: state `keys.fips` from the vendor's certificate, or remove it | `hsm-keys` |
| `MAIN-LOG-0020` | check | A password, key, token or authorization value is passed to a log call | `main27-baseline` |
| `MAIN-MIGRATE-0001` | CLI | `mainsdk migrate <from>` applied the codemods but `mainsdk check` or a locked flow failed, so the branch is kept and no pull request opens (400). Fix: Fix the finding on the `migrate/<from>` branch, then open the pull request by hand | `migration-guides` |
| `MAIN-MIGRATE-0002` | CLI | `mainsdk migrate <from>` could not start or finish: not a git repository, a working tree with changes, or a `git` or `gh` step failed (400 or 502). Fix: Commit or move your changes and run it in the app repository, or use `--report-only` to read the report without a branch | `migration-guides` |
| `MAIN-MOBILE-0001` | check | `targets.mobile` in `main.yaml` is not valid (missing or malformed bundle ID, permission, signing identity or name); the finding names the key | `expo-adapter` |
| `MAIN-MOBILE-0003` | check | Source writes a token, secret, password or refresh value to AsyncStorage or MMKV, which are not encrypted | `expo-adapter` |
| `MAIN-MOBILE-0004` | check | App source calls `fetch`, `XMLHttpRequest` or `axios` directly instead of the SDK client, so the network allowlist, audit and attestation do not apply | `expo-adapter` |
| `MAIN-NEIGHBOUR-0001` | check | `neighbours` is invalid: `host: on` with `apps.registry: off`, a `share` or `listen` name that isn't a signal name or glob, `priority` outside 1 to 9, `max-posture: lockdown`, `max-for` over 1h, or `asks.accept` with a verb outside the three | `neighbours` |
| `MAIN-NEIGHBOUR-0005` | check | `asks.accept` lists `posture.raise` or `load.shed` but `apps.link` is off or `apps.peers` is empty | `neighbours` |
| `MAIN-NET-0020` | check, runtime | A `tcp://`, `udp://` or `unix://` entry, a `network.listen` entry or a `network.udp` entry doesn't parse: no port, a port outside 1 to 65535, a range written high to low, an unknown protocol, IPv6 without brackets, a bind address that isn't an IP, or a unix path that is relative, not normalized, holds `..` or `*` (other than a final `/*` in `allow`) or is over 104 bytes (fails at load; names the entry) | `net-sockets` |
| `MAIN-NET-0025` | check, runtime | TLS verification turned off outside `dev` and `test`, or a minimum version below TLS 1.2 anywhere | `net-sockets` |
| `MAIN-NET-0028` | check, runtime | A raw socket on a target that can't run it: `net.listen`, `net.listenUnix` or `net.udp` on a serverless or edge target, `net.connect` or `net.connectUnix` on an edge target, or a unix socket call on Windows; names the target, the runtime and the fallback | `net-sockets` |
| `MAIN-NET-0029` | check | A `net.listen` port or UDP bind found in the code that `network.listen` doesn't declare | `net-sockets` |
| `MAIN-NET-0030` | check | A `network.listen` entry binds beyond loopback with no `from` (a warning, not a failure) | `net-sockets` |
| `MAIN-NET-0040` | check | The code calls a non-local host over plain `http://` | `main27-baseline` |
| `MAIN-NET-0041` | check | TLS below 1.2 is forced, or certificate checks are turned off | `main27-baseline` |
| `MAIN-NET-0050` | check | `Info.plist` or `app.json` turns off App Transport Security with `NSAllowsArbitraryLoads`, so the app can load plain http | `expo-adapter` |
| `MAIN-NET-0051` | check | `AndroidManifest.xml` or `app.json` allows cleartext traffic (`usesCleartextTraffic`), so the app can send data over plain http | `expo-adapter` |
| `MAIN-NORMS-0001` | check | A `norms` value is invalid: `every` outside 1m to 15m, an unknown `season`, metric or time zone, `learn` over 28d, `min-samples` under 10, `z` under 2, or `margin` outside 0% to 200% | `norms` |
| `MAIN-NOTIFY-0001` | check, runtime | The `notify` section of `main.yaml` is invalid or a provider block is missing (400) | `email-notify` |
| `MAIN-NOTIFY-0006` | check, runtime | A quiet-hours time is not `HH:MM` or a time zone is not a known zone (400) | `email-notify` |
| `MAIN-OPS-0001` | check | An `ops` value is invalid: `write: auto`, a port outside 1024 to 65535, or `http: on` in production without `ops.agent` declared under `agents` | `ops-mcp` |
| `MAIN-OPS-0005` | cli | `mainsdk ops mcp` found no running app with an ops socket for the given folder or project | `ops-mcp` |
| `MAIN-PACK-0001` | config | A pack is not a `pack@1` bundle: missing id or version, or not valid JSON (400). Fix: rebuild it with `mainsdk pack build` | `industry-packs` |
| `MAIN-PACK-0002` | config | A pack would weaken the baseline: a permit policy, or a label rule that is not a refusal, a requirement or a restriction (400). Fix: packs add forbid policies and tightening rules only | `industry-packs` |
| `MAIN-PACK-0003` | config | A pack defines a label that is not canonical (400). Fix: use personal, sensitive, child, phi or pan | `industry-packs` |
| `MAIN-PACK-0004` | config | A standard has no pinned version, or a control has no SCF mapping (400). Fix: write `standard: pci-dss-4.0.1` and `scf: <id>` | `industry-packs` |
| `MAIN-PACK-0005` | config | A pack policy is not valid Cedar (400). Fix: fix the syntax and rebuild the pack | `industry-packs` |
| `MAIN-PACK-0006` | config | A control names a check that does not exist (400). Fix: use one of the check kinds the pack reference lists | `industry-packs` |
| `MAIN-PACK-0008` | check | `industry` names a pack that is not in the verified cache or in `packs/`, or whose bundle does not verify; the last good version stays in force (400). Fix: run `mainsdk sync` to fetch the signed pack | `industry-packs` |
| `MAIN-PACK-0009` | usage | `assure --standard` or `pack build` was run without its value (400). Fix: pass the standard or the folder | `industry-packs` |
| `MAIN-PACK-0010` | check | A field has a label the pack refuses in any store, such as `pan` in the payments pack (400). Fix: the mapped fix, for payments "use hosted fields" | `industry-packs` |
| `MAIN-PACK-0011` | check | A field the pack needs encrypted is not, so reads cannot be audited (400). Fix: set `db.fields.<field>.encrypt` to true | `industry-packs` |
| `MAIN-PACK-0012` | check | A driver that can hold regulated data declares no signed business associate agreement (400). Fix: use a driver whose manifest declares `baa: true` | `industry-packs` |
| `MAIN-PACK-0013` | check | The pack does not allow the driver in use for an interface (400). Fix: use one of the drivers the pack lists | `industry-packs` |
| `MAIN-PACK-0014` | check | Audit logs are kept for less time than the pack needs (400). Fix: set `logging.retention` | `industry-packs` |
| `MAIN-PACK-0015` | check | Admin access does not require multi-factor authentication (400). Fix: set `auth.admin.require` to phishing-resistant | `industry-packs` |
| `MAIN-PACK-0020` | check | A third-party provider is used that the pack's provider register does not list (400). Fix: add it to `compliance.providers` with its reason and owner | `industry-packs` |
| `MAIN-PACK-0022` | check | Change control is not switched on, so releases are not reviewed (400). Fix: set `compliance.change-control` and require a reviewed pull request | `industry-packs` |
| `MAIN-PACK-0023` | check | No passing restore drill inside the pack's window (400). Fix: run `mainsdk drill restore --to scratch` and keep the signed evidence | `industry-packs` |
| `MAIN-PERM-0008` | check | A disk value is invalid: a `max` or `reserve` that isn't a size or a percentage, a `reserve` over 50%, or `temp` set to a folder | `app-permissions` |
| `MAIN-PLAT-0001` | check | A Tauri or Electron release build is unsigned, or its updater has no public key or uses plain http | `platforms` |
| `MAIN-PLAT-0002` | check | A browser extension is not Manifest V3, asks for a broad host permission with no declared need under `platforms.extension.needs`, or its CSP allows eval or remote scripts | `platforms` |
| `MAIN-PLAY-0001` | playground, cli | The tests file is not a list of tests with a name, an input and `allow` or `deny` as the expectation (400). Fix: write each test as `{ "name": "…", "input": { … }, "expect": "allow" }` | `policy-playground` |
| `MAIN-PLAY-0002` | playground, cli | The replay holds more recorded decisions than the playground replays at once (413). Fix: replay a smaller sample of at most 100000 decisions | `policy-playground` |
| `MAIN-PLAY-0003` | playground | The link does not hold a playground state this version can read (400). Fix: ask for the link again, or paste the policy and request in by hand | `policy-playground` |
| `MAIN-PLAY-0004` | playground | The state is too large to share, or getqr.id did not make the link (502 or 413). Fix: share without the replay, or share again when the connection is back | `policy-playground` |
| `MAIN-PLAY-0005` | cli | `mainsdk policy play` could not read a policy, request, entities, tests or replay file (400). Fix: pass a folder with policies and a request file that holds JSON | `policy-playground` |
| `MAIN-PLAYBOOK-0001` | check | A `playbooks` or `posture` value is invalid: an unknown step, preset, trust level or severity; a `for` over 24h; a `count` window under 1m; a `cooldown` under 1m; or a parameter that doesn't fit the step | `playbooks` |
| `MAIN-PLAYBOOK-0002` | check | A step's interface isn't configured or built (for example `bots.block` with no `bots` section, `workers.scale` before parallelism); `fix` names the spec | `playbooks` |
| `MAIN-PLAYBOOK-0003` | check, runtime | A step would not tighten: `limits.tighten` to a larger amount or another period, a flag that isn't defined, an agent that isn't declared; refused before anything runs | `playbooks` |
| `MAIN-PLAYBOOK-0010` | check | An action used as a step isn't marked `reaction: true`, or its `undo` names an action that doesn't exist | `playbooks` |
| `MAIN-POLICY-0007` | test | `mainsdk test policy --recorded` was given a folder that does not exist | `policy` |
| `MAIN-PRIV-0001` | check | A data label in use has no retention rule (`privacy.retention.<label>`) | `privacy-lifecycle` |
| `MAIN-PRIV-0004` | check | The `privacy` section of main.yaml does not read: an unknown key, a retention that is not a duration, or retries out of range | `privacy-lifecycle` |
| `MAIN-PYTHON-0001` | check | Ruff reported a rule in a Python project (the finding names the rule, the file and the line). Fix: Fix the code the rule points at, as its message says; never ignore the rule | `python-sdk` |
| `MAIN-PYTHON-0002` | check | Pyright reported a type error in strict mode. Fix: Fix the type error where it is reported; never add a `type: ignore` | `python-sdk` |
| `MAIN-PYTHON-0003` | check | Bandit reported a weakness in Python code. Fix: Fix the weakness Bandit names, using its more_info page | `python-sdk` |
| `MAIN-PYTHON-0004` | check | A Python check tool isn't installed, so its gate did not run (a warning, never a pass). Fix: Install it: `pip install ruff pyright bandit` | `python-sdk` |
| `MAIN-REPORT-0005` | check | `logging.errors` is invalid: `sentry` with no `dsn`, a `dsn` host not in `network.allow`, a `sample` outside 0 to 1, or `alert.spike.over` under 1 | `error-reporting` |
| `MAIN-RUST-0001` | check | Clippy reported a lint in a Rust project (the finding names the lint, the file and the line). Fix: Fix the code the lint points at, as its message says; never allow the lint away | `rust-sdk` |
| `MAIN-RUST-0002` | check | cargo-audit found a dependency with a known advisory (the finding names the advisory and the crate). Fix: Upgrade the crate to the patched version the advisory names | `rust-sdk` |
| `MAIN-RUST-0003` | check | cargo-deny refused a dependency for its licence, a ban, its source or an advisory. Fix: Replace the dependency, or change `deny.toml` with the owner's approval | `rust-sdk` |
| `MAIN-RUST-0004` | check | A Rust check tool isn't installed, so its gate did not run (a warning, never a pass). Fix: Install it: `rustup component add clippy`, `cargo install cargo-audit cargo-deny` | `rust-sdk` |
| `MAIN-SANITIZE-0003` | check | A raw HTML sink (`dangerouslySetInnerHTML`, `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`, `v-html`, `{@html}`) is fed by a value that doesn't come from `sanitize.html` or `sanitize.markdown` | `sanitize` |
| `MAIN-SECRET-0011` | check, runtime | A secret is past its `max-age` (fails `mainsdk check --env <env>` when the driver can report ages; a Main 27 exception covers it) | `secret-rotation` |
| `MAIN-SECRET-0014` | check | A `secrets.rotation` value is invalid: a bad duration, `overlap` longer than `max-age`, `generate` under 16 bytes, or a name the app doesn't reference | `secret-rotation` |
| `MAIN-SECURITY-0001` | check | A `security` value is invalid: an unknown severity, sink or detector, or a detector threshold below 2 | `security-events` |
| `MAIN-SECURITY-0002` | check | `to` includes `otel` and a region the app stores data in has no endpoint (no `regions.<r>` and no `telemetry.otel`) | `security-events` |
| `MAIN-SESSION-0001` | check | A token is written to `localStorage` or `sessionStorage` | `main27-baseline` |
| `MAIN-SESSION-0002` | check | A token is issued for longer than seven days | `main27-baseline` |
| `MAIN-SIGNAL-0006` | check | A `signals` value is invalid: `keep` outside 100 to 10,000, a TTL over `ttl.max` or over 24h, or `key` written as a literal instead of `secret:NAME` | `signals` |
| `MAIN-SIGNAL-0007` | check | Production uses a shared broadcast driver (`redis`) and app-scope signals, with no `signals.key`; another app on the same store could forge them | `signals` |
| `MAIN-SIM-0001` | test | An injection or option needs a spec that has no code yet (`attack`, `key`, `approve` without playbooks); the message names the spec | `intelligence-sim` |
| `MAIN-SIM-0002` | test | A sim input is invalid: an unknown app name, a start that is not a time, or a step that is not positive | `intelligence-sim` |
| `MAIN-SUPPLY-0001` | check | A dependency is `*`, `latest`, empty or fetched from a URL or git | `main27-baseline` |
| `MAIN-SYNC-0007` | check | A table under `sync.tables` has no whole-number `version`, or a `conflicts` value that is not `last-writer-wins`, `server-wins` or `action:<name>` | `sync` |
| `MAIN-TEAMS-0001` | cloud | The member's role does not allow this in the organisation (403). Fix: ask an admin of the organisation to change your role or to do it for you | `teams-plan` |
| `MAIN-TEAMS-0002` | cloud | The invite is unknown, used, past its seven days or sent to another email (410). Fix: ask an admin to invite you again | `teams-plan` |
| `MAIN-TEAMS-0003` | cloud | An add-on applies only to the projects of the buyer's own organisation, and none may offer what Fleet is for (403). Fix: buy it for a project your organisation owns | `teams-plan` |
| `MAIN-TEAMS-0004` | cloud | There is no such add-on, or it has no price yet (404 or 409). Fix: choose an add-on that is on sale | `teams-plan` |
| `MAIN-TEAMS-0005` | cloud | An annual invoice needs a purchase order number (400). Fix: pass the purchase order number of your finance team | `teams-plan` |
| `MAIN-TEAMS-0006` | cloud | The sign-in or SCIM request is not allowed: no code, or the person is not provisioned (400 or 403). Fix: assign the person to the MainSDK application in the identity provider | `teams-plan` |
| `MAIN-TEAMS-0007` | cloud | The organisation is not an approved startup (403). Fix: apply for the startup programme and wait for the approval | `teams-plan` |
| `MAIN-TEAMS-0008` | cloud | The evidence built for a project names another project (500). Fix: build the evidence again for the project it is pushed for | `teams-plan` |
| `MAIN-TEAMS-0009` | cloud | The project to transfer is not owned by the organisation giving it away (404). Fix: transfer a project your organisation owns | `teams-plan` |
| `MAIN-UPDATE-0003` | check | The `updates` section is invalid: a version that isn't dotted numbers, a rollout outside 0 to 100, a channel other than `stable` or `beta`, or a deprecation without a `path` and a `sunset` date | `updates` |
| `MAIN-UPDATE-0004` | check | `updates.min-version` is above the `stable` channel's version, so every current client would be blocked | `updates` |
| `MAIN-UPGRADE-0001` | CLI | The git working tree has uncommitted changes, or the folder isn't a git repository; nothing was changed | `upgrade` |
| `MAIN-UPGRADE-0002` | CLI, check | MainSDK packages are at different versions in the workspace; they move only together | `upgrade` |
| `MAIN-UPGRADE-0003` | CLI | A codemod couldn't run (no `typescript` in the app, or a file didn't parse); it is listed as a manual step with file and line | `upgrade` |
| `MAIN-UPGRADE-0004` | CLI | The registry couldn't be reached, so the target version is unknown; nothing was changed | `upgrade` |
| `MAIN-UPGRADE-0005` | CLI, check | A release marked `security` is newer than the installed version | `upgrade` |
| `MAIN-UPGRADE-0006` | CLI | After the upgrade, the install, `sync`, `check` or the app's tests failed; the branch is kept and the pull request is a draft listing the failures | `upgrade` |
| `MAIN-UPGRADE-0010` | tools | A release's API report has a removed or changed export with no upgrade note entry, or an entry's codemod has no fixture | `upgrade` |
| `MAIN-VAULT-0006` | config | `ai.redact.driver` is unknown, or `agentcloak` has no client (500). Fix: set `built-in` or `agentcloak` and pass the client | `residency-vaults` |
| `MAIN-VERIFY-0004` | check, runtime | A market requires an identity level its driver cannot reach, or no driver serves it (check); an identity call asked for a level above the driver's reach (runtime, 422) | `verify` |
| `MAIN-VERIFY-0006` | check, runtime | The `verify` section is not valid, a driver is not built, or an email check has no app origin, share or email (500) | `verify` |
| `MAIN-WEB-0001` | check | Open CORS: `origins` contains `*` with `credentials: true` (any env), or `*` at all with `--env prod` | `inbound-protection` |
| `MAIN-WEB-0003` | check | An `inbound` value is invalid: a bad origin or host, a bad duration, a route pattern that matches nothing, or an unknown key | `inbound-protection` |
| `MAIN-WEB-0007` | check | The CSP allows `'unsafe-inline'` or `'unsafe-eval'` in `script`, or `*`, `http:` or `https:` alone as a script source | `inbound-protection` |
| `MAIN-WEB-0009` | check | Code sets a cookie with `SameSite=None` without `Secure`, or `httpOnly: false` for a cookie not in `cookies.readable` | `inbound-protection` |
| `MAIN-WEB-0010` | check | `security-txt` has no `contact`, or `expires` is missing, in the past, or more than one year after the build date | `inbound-protection` |
| `MAIN-WEB-0011` | check | No `security-txt` in a production app (a warning, not a failure) | `inbound-protection` |
| `MAIN-WORKER-0001` | check | `node:worker_threads`, `node:cluster` or `child_process.fork` used outside the SDK | `parallelism` |
| `MAIN-WORKER-0009` | check | A `workers` or `cluster` value is invalid: a size, `processes` or `queue` out of range, a `memory` that isn't a size, a module glob that matches no file, a module in two pools, or an `env` name that is a secret's name | `parallelism` |
| `MAIN-WORKER-0010` | check | Workers or cluster on a target that can't run them: cluster with more than one process on serverless, edge or Deno fails; workers on a runtime without threads warn that tasks run inline | `parallelism` |
| `MAIN-WORKER-0016` | check | A worker module or `cluster.run` found in the code that `main.yaml` doesn't declare | `parallelism` |
<!-- codes:end -->

## Next

- [Errors and problem details](https://mainsdk.dev/docs/reference/errors)
- [Your first check](https://mainsdk.dev/docs/getting-started/first-check)
- [The check](https://mainsdk.dev/docs/concepts/the-check)