# Error codes

> The nine error codes every Emolysis surface returns, what each one means, the usual causes, and what to do about it when one appears.

Every Emolysis command returns either a result or a typed error. It does not crash, hang or print a stack trace at you. The error has one of nine codes, a one-line message, and details. The desktop app, the `emo` command line and the MCP server all return the same codes, so a script or a coding agent can decide what to do from the code alone.

## What an error carries

| Part      | What it is                                                                               |
| --------- | ---------------------------------------------------------------------------------------- |
| `code`    | One of the nine codes below                                                              |
| `message` | One line that tells a person what happened and what to do                                |
| `details` | A JSON object with the context: which parameter, which table, the platform's own message |

Details hold no secrets and no customer rows. When you report a problem, include the code and the details.

```json
{
  "error": {
    "code": "not_found",
    "message": "template 'scd2.databricks' not found",
    "details": { "id": "scd2.databricks" }
  }
}
```

The example is illustrative. On the command line, `emo run` prints an object like this and exits with status 1; in an MCP client, a failed tool call is an error result that carries the same object. Branch on `code`, never on the message.

## The nine codes

### `invalid_params`

A parameter is missing, has the wrong type, is out of range, or is not allowed. This also covers invalid input such as SQL that does not parse, a slot value of the wrong type or a chart spec that breaks a rule.

**What to do.** Check the command's parameters with `emo commands --schemas`. The details list which parameters failed and why.

### `not_found`

Something you named does not exist: a command id, a table, a template, a project, a workspace, a file or a dashboard link.

**What to do.** Check the name and the connected workspace. For a dashboard link, it may have been revoked or expired, or you may not have access; the answer looks the same either way. See [Sharing dashboards](https://emolysis.com/docs/sharing).

### `not_implemented`

The command or option exists, but is not built for this case yet. Typical cases: OAuth sign-in on Snowflake, or a dashboard export to Snowflake or Fabric.

**What to do.** Use another platform or shape, or wait for support. The template matrix shows which cells are green, yellow or missing. See [Templates and slots](https://emolysis.com/docs/templates).

### `auth_required`

You are not signed in, a connection has no credentials, or your session expired.

**What to do.** Sign in again. Emolysis prints or shows a short code; confirm it in the browser, where you sign in with your GitHub, Microsoft or Google account. The code expires after 15 minutes. For a platform, reconnect it. See [The MCP server](https://emolysis.com/docs/mcp-server) for signing in from an editor.

### `platform_error`

Your platform, or DuckDB, failed the operation. The platform's own message is in the details. Timeouts on external calls are reported this way too.

**What to do.** Read the platform's message. The usual causes are missing permissions, a stopped or unavailable compute resource, and identifiers that fold case. See [Troubleshooting](https://emolysis.com/docs/troubleshooting) and [Connecting Databricks](https://emolysis.com/docs/connect-databricks).

### `conflict`

The action clashes with the current state: a version mismatch, a concurrent edit, a target that already exists, or an artifact written for another platform.

**What to do.** Refresh, then retry. If you meant to deploy a file to another platform, use an explicit translation step. See [Deploying](https://emolysis.com/docs/deploying).

### `internal`

Something failed inside Emolysis that is not covered by another code. This is a bug on our side, not a problem with your input.

**What to do.** Retry. If it repeats, include the details when you report it; see [Troubleshooting](https://emolysis.com/docs/troubleshooting).

### `insufficient_credits`

Your plan has no model usage left for the request: its included usage is used up, and usage credits are off or have reached the spend limit you set. On Enterprise, a spend limit that an admin set has been reached.

**What to do.** Wait for the limit to reset, switch the agent to your own model key, move to a plan with more included usage, or turn on usage credits (or raise the spend limit you set for them). On Enterprise, ask an admin to raise your spend limit. Work that does not need the model, such as golden tests on DuckDB, keeps working. See [Model keys and credits](https://emolysis.com/docs/model-keys-and-credits).

### `rate_limited`

Too many requests arrived from you in a short time, and the service is asking you to slow down. The error says how many seconds to wait, in its details and in the `Retry-After` header.

**What to do.** Wait that long, then try again. A script or agent should back off for the time given instead of retrying at once.

## Which surface shows what

| Surface     | How an error appears                                              |
| ----------- | ----------------------------------------------------------------- |
| Desktop app | A message with the code and details, next to the step that failed |
| `emo`       | A JSON error object on `emo run`, and exit status 1               |
| MCP server  | A tool result marked as an error, with the same typed error       |

## Status

The nine codes are fixed. The message texts, the details fields and the way each surface shows them can change before the first release.

---

Page: https://emolysis.com/docs/error-codes. Emolysis is a product of Bandpey GmbH, Munich, Germany. It is in private development, and nothing is released yet.