> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish, debug, and troubleshoot

> Publishing is a transaction that can roll back. When something fails, start from the structured result the host returns.

<div className="code-docs">
  <h2 id="pipeline">
    Publishing flow
  </h2>

  A Mini App never runs straight from its installation directory. When publishing, the host:

  <Steps>
    <Step title="Stages">
      Copies the package to a host-managed staging area. Dependency directories aren't published. After copying, it rereads the manifest and file digests, and publishing fails if they changed.
    </Step>

    <Step title="Installs">
      Moves the previous version into quarantine, atomically swaps the staged copy into the installation directory, and checks the digests again.
    </Step>

    <Step title="Starts">
      Makes a separate runtime copy from the installation directory, verifies its identity, and starts it in its own process. The old process stops first, and the new one takes over only once it is ready.
    </Step>
  </Steps>

  If any install step fails, the previous version moves back from quarantine and the installation directory is restored. If the old process has stopped and the new one fails to start, the host doesn't revive the old process; run `open`, `publish`, or `restart` again. Skills and ordinary MCP in the package are unaffected. See [Updating a running Mini App](/docs/miniapp/host/lifecycle#transaction).

  <h2 id="inspect">
    Check runtime status
  </h2>

  `inspect` is read-only and never starts or restarts the service. It mainly returns:

  * `source`: `official` or `local`, set by the host from its install records.
  * `diagnostics.run`: the current or latest run, with preparation and readiness times and any confirmed exit details.
  * `diagnostics.failure`: the failure the host currently reports.
  * `diagnostics.logs`: host records of startup, readiness, failures, and exits, with a size limit.

  Diagnostics live only in host memory and are cleared when the host restarts. Treat missing times, exit codes, and failure reasons as unknown; don't guess.

  <h2 id="debug">
    Debug the page
  </h2>

  Run `open` first, then use the built-in browser's inspect, query, click, and type actions to check structure, text, controls, and state. Lifecycle actions (publish, restart, stop) always go through the `miniapp` tool, never through browser actions.

  <h2 id="faq">
    Common problems
  </h2>

  | Symptom | Cause | Fix |
  | - | - | - |
  | `READINESS_TIMEOUT` | `start` never returned; the assigned port isn't served by `node:http`; or your routes shadow `/__mavis/` | Listen and install routes before returning; serve the assigned port with `node:http` |
  | `BUSY` · `capacity_busy` | Three Mini App services are already running | Stop one you don't need, then retry once |
  | `BUSY` · `operation_busy` | Another operation on the same Mini App is in progress | Wait, then retry once |
  | `PLUGIN_ALREADY_EXISTS` | With `OFFICIAL_PLUGIN_READ_ONLY`, the name matches an installed official plugin | Official plugins can't be edited locally; use another `pluginId` |
  | `PREPARATION_FAILED` | Publish preparation failed | Follow the returned `diagnostic.recovery` and `hint` |
  | `INTERNAL_ERROR` | Internal host error, with a `diagnosticId` | Don't retry as is; `lastGoodAvailable` says whether the previous version still works |
  | Page returns `401` | After a restart, an open tab still holds the old credential | Refresh or reopen the page |
  | The Agent can't use the Mini App's tools | The managed MCP handler fails, or `mcpEndpoints` doesn't match the implemented path | Fix it and publish again |

  See [Error codes](/docs/miniapp/reference/errors) for the full list.
</div>