Errors and problem details

Every error MainSDK raises tells you, or your agent, what failed, where in your own code, which main.yaml rule was involved and how to fix it. Errors follow open standards so any tool can read them:

The problem body

{
  "type": "https://mainsdk.dev/errors/MAIN-DATA-0007",
  "title": "Record belongs to another user",
  "status": 403,
  "detail": "orders.get was called for an order owned by a different user.",
  "instance": "/api/orders/8812",
  "code": "MAIN-DATA-0007",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "rule": "data.owner_scope",
  "fix": "Scope the query with db.orders.for(user).",
  "retryable": false
}

In production, response bodies sent to end users never carry file, line, function or a stack trace. Those stay in your logs.

Throw a MainError

MainError builds the body for you. Codes are a generated union type, so a typo doesn't compile.

import { MainError } from "mainsdk";

throw new MainError("MAIN-DATA-0007", {
  rule: "data.owner_scope",
  fix: "Scope the query with db.orders.for(user).",
});

Inside a route wrapped by an adapter, such as withMainSDK from mainsdk/next, the thrown error becomes the problem body above, with status 403 and the request's trace_id. An unknown error, such as a TypeError, becomes MAIN-CORE-0500 with no internal detail in production. Outside an adapter, call err.toProblem(instance) yourself.

// mainsdk/log
class MainError extends Error {
  constructor(code: ErrorCode, opts?: { detail?: string; fix?: string; cause?: unknown;
    rule?: string; retryable?: boolean; status?: number });
  readonly code: ErrorCode;          // "MAIN-<AREA>-<NNNN>"
  toProblem(instance?: string): Problem;
}

interface Problem {                  // application/problem+json, RFC 9457
  type: string; title: string; status: number; detail: string; instance?: string;
  code: ErrorCode; trace_id?: string; function?: string; file?: string; line?: number;
  rule?: string; fix?: string; retryable: boolean;
}

The same error in your logs

Each error is also a log record with OpenTelemetry exception attributes and code location, linked to its request by the trace ID, so your agent can find the cause without guessing:

{
  "timestamp": "2026-11-03T10:14:02Z",
  "severity": "ERROR",
  "body": "Record belongs to another user",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "attributes": {
    "exception.type": "MainError",
    "exception.message": "orders.get was called for an order owned by a different user.",
    "code.function.name": "getOrder",
    "code.file.path": "app/api/orders/[id]/route.ts",
    "code.line.number": 18
  }
}

The exception.* and code.* names are OpenTelemetry's. The attribute names for MainSDK's own fields (code, rule) come with the telemetry@1 contract.

Stack frames point at your source, not at SDK internals, through the source maps shipped with every package.

What is redacted

Before an error is written, returned or exported, MainSDK replaces:

• values of fields labelled personal, sensitive, child or phi with [redacted:personal] and so on;
• anything resolved from a secret: reference, and known key formats such as msk_live_…, with [redacted:secret].

Codes

Every code is declared once in the contract source with its title, HTTP status, default fix, retryable flag and docs text. Removing a code, or changing what it means, is a breaking change that mainsdk contract diff fails. Every code defined so far, including areas other specs add (such as KEYS, PRIV, NOTIFY, MCP, REALTIME and HOOK), is listed in check codes.

Runtime errors from seal and apps

These runtime codes come from the build seal (spec seal) and the app registry (spec app-registry). Every other code is in check codes.

Runtime errors from memory

These runtime codes come from agent memory (spec memory, planned for 0.4). The check findings MAIN-MEM-0020 to MAIN-MEM-0025 are in check codes.

Runtime errors from the API and the typed client

These runtime codes come from the specs app-api. Each one also has a row in check codes.

Runtime errors from imports, connections and MCP

These runtime codes come from the specs imports, connections. Each one also has a row in check codes.

Runtime errors from seed, preview, analytics and engagement

These runtime codes come from the specs seed-preview, analytics, engagement. Each one also has a row in check codes.

Runtime errors from workflows, realtime and health

These runtime codes come from the specs workflows, realtime, health. Each one also has a row in check codes.

Runtime errors from search, feeds, moderation and media

These runtime codes come from the specs search, feeds, moderate and media, all planned for 0.4. Each one also has a row in check codes.

Runtime errors from protect

These runtime codes come from protected files (spec protect-taps, planned for 0.4). A denial carries the TAPS error type in a taps member and never names the failed condition. Each one also has a row in check codes.

Runtime errors from licence

These runtime codes come from app licensing (spec licence, built; codes from 0020 come from MainSDK Cloud, spec licence-cloud, planned for 0.6). A refusal never includes the licence's claims, its id or the machine id. Each one also has a row in check codes.

Runtime errors from share and links

These runtime codes come from share (spec files-share, ADR-0056) and links (spec links, planned for 0.4), and from the sign-in link method of auth. The check findings MAIN-SHARE-0001, MAIN-SHARE-0007 and MAIN-LINK-0003 to MAIN-LINK-0005 are in check codes.

Runtime errors from the modern AI specs

These runtime codes come from multimodal input, images, video, the agent loop, routing and local models (specs ai-multimodal, ai-image, ai-video, ai-run, ai-routing, ai-local), documents (documents), sandboxes (sandbox), languages (i18n) and voice agents (ai-voice). Their check findings, and the EVAL codes the CLI raises, are in check codes.

Runtime errors from db and kv

These runtime codes come from db (specs db, db-writes and db-queries) and kv (spec kv). The check findings MAIN-DATA-0013, MAIN-DATA-0020, MAIN-DATA-0021, MAIN-DATA-0030, MAIN-DATA-0040 to MAIN-DATA-0045, MAIN-DATA-0051, MAIN-DATA-0055, MAIN-DATA-0056, MAIN-DATA-0061, MAIN-DATA-0062 and MAIN-DATA-0065 are in check codes.

Codes from other specs

These runtime 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.

Debug an error

$ npx mainsdk explain 4bf92f3577b34da6a3ce929d0e0e4736
MAIN-DATA-0007  Record belongs to another user
at     app/api/orders/[id]/route.ts:18 (getOrder)
rule   data.owner_scope
fix    Scope the query with db.orders.for(user).

mainsdk explain works offline from the local registry and event store. To see each provider call (driver, operation, duration, status, with bodies and headers redacted), set MAINSDK_DEBUG=driver. In production it is refused with MAIN-LOG-0003 unless a debug session allows it; see environment variables.

Errors from MainSDK Cloud

When the Free allowance runs out after the warning and grace period, MainSDK Cloud answers 402. Only the Cloud: your app keeps running and every check keeps working.

{ "type": "https://mainsdk.dev/errors/MAIN-CLOUD-0402", "title": "Free allowance used",
  "status": 402, "detail": "50,000 events used this month. Add a card or move to Teams.",
  "upgrade": "https://mainsdk.dev/billing?prj=prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY" }

Next

• Check codes
• Debugging
• Environment variables