Error reference

This page describes Mini App interfaces available in official releases and their error handling, with version differences noted in the relevant sections. Method signatures are in Client API, Node API, and Agent API.

Identify the error shape first

Entry point	Read	Recovery basis
Page `window.mcode.miniapp`	The thrown or rejected `Error.message`, using lowercase codes	Use the method’s table; do not assume Node `code`, `reason`, or `permissions` survives the page bridge
Node `context.hostConnector` / `context.tool`	`code`, `disposition`, `retryable`, and optional `invocationId` and `diagnostic`	`disposition` determines dispatch state; the same timeout or cancellation code can have different outcomes
Node `context.agent`	`code`, `retryable`, and possibly `reason` with `BUSY`	`retryable` means nothing started and the call may be retried later; do not repeat a turn with an unknown outcome
The Agent’s `miniapp` lifecycle tool	`{ ok: false, action, error }`	Inspect `error.code`, `retryable`, and optional `diagnostic`; this is not a rejected page Promise

Do not depend on instanceof or a concrete Error subclass across process boundaries. Use message for display or diagnostics and code for Node business branches.

miniapp tool

These errors belong to the Agent tool used for init, publish, open, inspect, restart, and stop, rather than Node context.tool.

`error.code`	Meaning and handling
`INVALID_ARGUMENTS`	Invalid action or argument combination; correct it before retrying
`NOT_FOUND`	The Mini App was not found; check `pluginId` and installation
`NOT_ENABLED`	The plugin is disabled; enable it first
`PLUGIN_ALREADY_EXISTS`	A plugin with the same name exists; inspect `diagnostic`, and do not overwrite an official package with local publishing
`BUSY`	Inspect `busyReason`: `operation_busy` means another action is in progress; `capacity_busy` means all three runtime slots are taken and a slot must be freed
`SERVICE_RESTARTED`	The service generation changed during the action; refresh state and follow `retryable`
`PREPARATION_FAILED`	Package, manifest, installation, or startup preparation failed; follow `diagnostic.recovery` and `hint` below
`RUNTIME_FAILED`	The runtime could not complete the action; inspect `runtimeError` and `inspect` rather than treating this as one root cause
`OPEN_UNAVAILABLE`	This host provides no surface for opening the page
`INTERNAL_ERROR`	Internal host failure; may include `diagnosticId` and `lastGoodAvailable`; retain diagnostics and do not repeat unchanged
`CANCELLED`	The action was cancelled; the user or application decides whether to start again

error.retryable is a host recovery hint. Retrying capacity_busy does not free a slot. Even when PREPARATION_FAILED suggests a retry recovery, satisfy the condition in its hint first.

Publishing diagnostics

error.diagnostic has { stage, reasonCode, recovery, hint }. stage is workspace, runtime, mcp, connector, or host; recovery is edit_workspace, retry, or user_action. The following are public publishing reasonCode values, not top-level error.code values.

`reasonCode`	What to check
`OFFICIAL_PLUGIN_READ_ONLY`	Official plugins cannot be edited or republished locally; accompanies `PLUGIN_ALREADY_EXISTS`
`MINIAPP_WORKSPACE_CANDIDATE_MISSING`	No candidate package in the current workspace; pass a finished directory with `sourcePath`
`MINIAPP_SOURCE_UNAVAILABLE`, `MINIAPP_SOURCE_INVALID`	Whether the supplied directory is readable and contains a complete package
`MINIAPP_SOURCE_IDENTITY_MISMATCH`, `MINIAPP_SOURCE_OVERLAP`	Whether the package matches `pluginId` and the source overlaps the installation directory
`WORKSPACE_PLUGIN_INVALID`, `MINIAPP_REFERENCE_INVALID`	`plugin.json` and the declaration entry in `package.json`
`MINIAPP_MANIFEST_INVALID`, `MINIAPP_MANIFEST_FIELD_UNSUPPORTED`	Manifest format, schema, and whether the host recognizes its fields
`MINIAPP_ARTIFACTS_INVALID`, `MINIAPP_RUNTIME_INVALID`, `MINIAPP_RUNTIME_ENTRY_INVALID`	Payload roots, process runtime declaration, and entry coverage
`MINIAPP_SURFACE_INVALID`, `MINIAPP_MCP_ENDPOINTS_INVALID`	Page route, window fields, and MCP endpoint declarations
`MINIAPP_CONNECTOR_ACCESS_INVALID`, `MINIAPP_AGENT_ACCESS_INVALID`, `MINIAPP_TOOL_ACCESS_INVALID`, `MINIAPP_DEVICE_ACCESS_INVALID`	Permission names, values, and host support
`MINIAPP_AGENT_CONCURRENCY_INVALID`	Whether concurrency is an integer from 1 to 32
`MINIAPP_ENGINES_INVALID`	Whether `engines.mcode` uses the supported `>=MAJOR.MINOR.PATCH` syntax
`MINIAPP_HOST_TOO_OLD`	Whether the host satisfies `engines.mcode`; update it or verify that the package needs this minimum
`WORKSPACE_CHANGED`, `WORKSPACE_INSTALL_FAILED`	Concurrent edits during preparation, local installation conflicts, or file access
`RUNTIME_START_FAILED`, `RUNTIME_START_EXPORT_MISSING`, `RUNTIME_LIFECYCLE_INVALID`, `RUNTIME_NOT_READY`	Entry loading, the `start` export, its return value, and readiness
`MCP_INVENTORY_INVALID`, `MCP_INVENTORY_MISMATCH`, `MCP_PUBLICATION_INVALID`	MCP tool inventories, digests, and safe publication
`MCP_ENDPOINT_UNREACHABLE`, `MCP_PROTOCOL_INVALID`	Whether each endpoint is running and returns valid protocol responses
`HOST_CONNECTOR_UNAVAILABLE`, `HOST_CONNECTOR_PROTOCOL_INVALID`	Host bridge availability and use of the public Connector API
`HOST_CAPACITY_UNAVAILABLE`	Whether to stop an unused Mini App or wait for the current action

Node outcomes and retries

Host Connector and the unified tool entry share these error fields:

interface HostCallError extends Error {
  code: string; // Public codes are listed below.
  disposition: 'not_dispatched' | 'provider_reported' | 'unknown_after_dispatch';
  retryable: boolean;
  invocationId?: string;
  diagnostic?: {
    issues: { path: string; constraint: string; limit?: number }[];
  };
}

not_dispatched: nothing was sent to the target; address the cause before considering a retry.
provider_reported: the provider returned a failure. Interpret its business outcome; this does not prove that no write occurred.
unknown_after_dispatch: the call may have executed. Read business state first and do not repeat a write based only on an error name or retry hint.
invocationId correlates the call and may be absent. diagnostic.issues contains safe field paths, constraints, and limits, not user argument values.

Host Connector

Node `code`	Meaning and handling
`TOOL_REF_STALE`	The reference expired; call `list()` again instead of constructing a `toolRef`
`SERVICE_RESTARTED`	The service restarted before dispatch; list tools again and check current state
`REQUEST_CANCELLED`	The request was cancelled; still inspect `disposition` rather than inferring non-execution from its name
`CONNECTOR_TIMEOUT`	Waiting timed out before dispatch; loss of confirmation after dispatch is treated as an unknown outcome
`INVALID_ARGUMENTS`	Invalid local input, arguments that do not match the schema, or a request exceeding the 256 KiB JSON limit; inspect `diagnostic.issues` when present and reduce oversized arguments
`CONNECTOR_NOT_PERMITTED`	The user switched this provider off; nothing was sent and the user must re-enable it
`CONNECTOR_PROVIDER_ERROR`	The provider reported a failure; this does not always mean authorization expired
`CONNECTOR_UNAVAILABLE`	Connector calls are unavailable for this generation; follow `retryable`
`CONNECTOR_OUTCOME_UNKNOWN`	Confirmation was lost after dispatch, including transport failure, timeout, or cancellation; reconcile business state first

See Node API for signatures and result structures.

Node unified tool entry

context.tool uses the Node error shape above. Calling a Connector tool can also retain Host Connector codes.

Node `code`	Meaning and handling
`INVALID_ARGUMENTS`	Invalid tool name, JSON arguments, permission request list, or a request exceeding the 256 KiB JSON limit; confirm names and schemas with `list()` and reduce oversized arguments. `diagnostic` may be absent
`TOOL_NOT_PERMITTED`	Missing call access, `tool:call` switched off, a `deny` rule, or the user denied this call
`TOOL_APPROVAL_REQUIRED`	Confirmation is needed but nobody can answer; request permission from an interactive host surface
`TOOL_UNAVAILABLE`	Tools are unavailable for this process generation or channel
`TOOL_REF_STALE`	The runtime tool name is no longer available; list again
`TOOL_TIMEOUT`	The approval or execution phase timed out; `disposition` distinguishes no dispatch from an unknown outcome after dispatch
`TOOL_RESULT_TOO_LARGE`	The result exceeded the response-frame limit; the call may have executed, so inspect `disposition` and reduce the business result
`TOOL_OUTCOME_UNKNOWN`	A dispatched result cannot be confirmed or represented safely as JSON; reconcile business state first
`MCP_SERVER_UNAVAILABLE`	The MCP server is unavailable; follow `retryable` after restoring it
`REQUEST_CANCELLED`	The call was cancelled; cancelling after dispatch does not guarantee rollback at the target
`SERVICE_RESTARTED`	The child-to-host channel was replaced; obtain tools and state again

When nobody can approve Node request(names), it rejects with TOOL_APPROVAL_REQUIRED and attaches a permissions snapshot for display. With only tool:call switched off, request() succeeds with every name mapped to deny and shows no prompt; this differs from a rejected call(). An MCP result with isError: true is a tool-reported business failure, not a rejected Promise.See Node API for signatures and result unions.

Agent API

Node reads error.code, error.retryable, and possibly error.reason with BUSY. Pages read Error.message; this table is the host mapping, not a lowercase transformation of Node names.

Node `code`	Page `message`	Meaning and handling
`NOT_PERMITTED`	`not_permitted`	Required `session.run` / `session.read` missing, switched off, or not authorized for this operation; the two grants do not imply one another
`BUSY`	`busy`	A busy session, full queue, start-rate limit, or full observer set; Node distinguishes the reasons below
`SESSION_NOT_FOUND`	`session_not_found`	The session does not exist, is not owned by this Mini App, or is not visible; do not bypass ownership
`INVALID_ARGUMENTS`	`invalid_request`	Invalid arguments, model, target combination, or questionnaire answers
`AGENT_UNAVAILABLE`	`runtime_unavailable`	The operation could not start, or a read/observation is unavailable; follow Node `retryable`
`REQUEST_CANCELLED`	`cancelled`	Cancelled before dispatch; cancellation after a turn starts usually returns `status: 'aborted'`
`AGENT_OUTCOME_UNKNOWN`	`result_unknown`	A turn or write may have occurred; do not resend automatically
`REQUEST_NOT_FOUND`	`request_not_found`	The approval or questionnaire does not exist, was already answered, or is outside the caller’s answer scope

Node BUSY.reason is session_busy, queue_full, rate_limited, or observer_limit. whenBusy handles follow-ups to busy sessions, not other limits. Pages may also receive busy for a duplicated in-flight requestId; do not rely on an attached page reason, because the bridge only guarantees the error message.Page transport failures also depend on the method: bridge failures for run, answer, reply, open, models, agents, and create may yield result_unknown; failures for observe, sessions, and session yield runtime_unavailable. Not every read-only method uses the same transport error.See Agent API for methods, returned error fields, and events. A fulfilled run() with status: 'error' differs from a rejected Promise; handle result status as well as catch.

Page APIs

Pages do not read Node code, retryable, or disposition. The following codes are thrown or rejected Error.message values. capabilities.has() is synchronous and returns a boolean; see Capability detection.

message.append

`message`	Meaning and handling
`user_cancelled`	The user cancelled confirmation; nothing was appended, and do not immediately prompt again
`invalid_request`	The argument is not a string or the request is malformed
`text_too_large`	More than 100,000 UTF-16 code units; shorten the text
`not_allowed`	The page identity or operation is not allowed
`target_unavailable`	The target is not writable, was deleted, or is unavailable; no fallback to another draft
`result_unknown`	Text may have been appended; inspect the target input before repeating

Window handle

The table describes v3.1.10 window behavior. Differences in v3.1.9 are noted below it.

`message`	Meaning and handling
`invalid_request`	Invalid patch field, numeric range, or listener type
`inline_mode`	The page is in the file panel and this action needs a standalone window
`not_permitted`	Missing user gesture, a requested window capability exceeds the manifest grant, or the updated window does not overlap one display’s work area by at least 40 px on both axes
`busy`	This page already has a transfer confirmation, mode switch, or rebuild in progress, or the same host window is confirming another Mini App’s transfer; wait for the current operation to finish
`result_unknown`	Page identity, response, or transport cannot be confirmed; reconcile with `getState()`

not_found is an internal window response and is not exposed as a page code; the page receives result_unknown. See Client API for methods and writable fields.In v3.1.10, cancelling confirmation for a transfer that rebuilds the page resolves update() with the current state and the original mode, without user_cancelled or busy; inspect the returned mode. Active page requests or subscriptions no longer block a transfer by themselves. After confirmation, they are cancelled or cleaned up when the old page ends. Promises and listeners from the old document do not survive; see Page rebuilds and confirmation.In v3.1.9, active requests, observation subscriptions, permission prompts, or capture can also make a transfer return busy. A page with a microphone grant has a separate transfer confirmation, where cancellation also returns busy. Do not apply the v3.1.10 cancellation rule to these older hosts.

Tool preauthorization

`message`	Meaning and handling
`invalid_request`	No user gesture, or the list is not 1–10 distinct valid runtime tool names
`not_permitted`	The calling page’s identity or current permission does not permit this request
`approval_required`	A tool needs confirmation but no host approval prompt can be shown
`runtime_unavailable`	No usable Node tool session, or the host tool channel is unavailable
`result_unknown`	Response, timeout, or bridge outcome is unknown; read current permissions rather than treating an old snapshot as a grant

With only tool:call switched off, page tool.request() succeeds with all names mapped to deny; it does not reject with not_permitted. Unlike Node’s method, page failure exposes only the code. Do not depend on error.permissions, even if the host response contained a snapshot. See Client API.

Speech transcription

`message`	Meaning and handling
`invalid_request`	Invalid input, exact format, sample bytes, or encoded container; convert to the required PCM first
`not_permitted`	Microphone undeclared, switched off, or caller is not a managed Mini App page
`audio_too_large`	More than 16,000,000 bytes or the host transcription duration limit
`busy`	Another transcription from this plugin is in flight; wait for it to end
`runtime_unavailable`	Host speech recognition disabled, no sign-in, or a session could not be established
`transcription_failed`	Upstream failure, transcription deadline, or page lifecycle ended; the deadline is currently 180 seconds
`result_unknown`	Response or bridge failure; the page has no handle for resuming the original request

Transcription returns text and does not cancel or stop the page’s capture stream. See Client API for format, results, and onPartial. Standard microphone and camera capture errors, such as NotAllowedError, come from the browser API rather than this transcription table.

Camera and system notifications

These capabilities are officially supported from MiniMax Code v3.1.9. They use standard browser APIs and have no additional host error codes.If getUserMedia() fails, read the browser exception’s name, such as NotAllowedError. Handle notifications through the standard Notification API: check Notification.permission and the result of requestPermission(), and listen for the notification object’s error event. Actual display also depends on system notification settings. Do not interpret these results as the speech transcription error codes above. See Page device APIs for declarations and usage.

Capability detection

capabilities.has(name) synchronously returns boolean; an unknown name returns false. It has no host error code or rejected Promise. Older hosts may omit the object, so check with optional chaining. Calling a missing object produces a JavaScript error, not a Mini App permission failure. See Client API for names and surfaces.

Startup and runtime diagnostics

inspect exposes diagnostics.failure.code, diagnostics.run.failure.code, and log code fields for runtime investigation. They are different layers from the lifecycle tool’s error.code and diagnostic.reasonCode. For example, a low-level READINESS_TIMEOUT helps locate listener/readiness problems, while the public publishing diagnostic uses RUNTIME_NOT_READY.Check that the entry exports start(context), binds the assigned port with node:http, and returns after the listener and routes are installed. Keep missing exit, time, and failure details unknown; a diagnostic name alone does not prove process exit. See Node API, Port authentication, and Publishing and troubleshooting.

Get started

Learn

Develop

Reference

Identify the error shape first

miniapp tool

Publishing diagnostics

Node outcomes and retries

Host Connector

Node unified tool entry

Agent API

Page APIs

message.append

Window handle

Tool preauthorization

Speech transcription

Camera and system notifications

Capability detection

Startup and runtime diagnostics

​Identify the error shape first

​miniapp tool

​Publishing diagnostics

​Node outcomes and retries

​Host Connector

​Node unified tool entry

​Agent API

​Page APIs

​message.append

​Window handle

​Tool preauthorization

​Speech transcription

​Camera and system notifications

​Capability detection

​Startup and runtime diagnostics

Identify the error shape first

miniapp tool

Publishing diagnostics

Node outcomes and retries

Host Connector

Node unified tool entry

Agent API

Page APIs

message.append

Window handle

Tool preauthorization

Speech transcription

Camera and system notifications

Capability detection

Startup and runtime diagnostics