> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Error codes and messages, with their fixes

> Look up a Meridian error code or message from the CLI, a deploy, readiness checks, Meridian MCP or the SDK, and jump to the page that explains the fix.

Every code and message prefix Meridian gives you, in one place. Each line says what it means in a few words and links to the section that explains the fix. Search this page for the exact text you got.

## Deployments

A failed deployment carries an `error_code` and an `error_message`. See [Why a deploy fails](https://help.the-meridian.ai/deployment.md#why-a-deploy-fails).

| Code or message | Means | Fix |
| - | - | - |
| `invalid_config` | A readiness check failed before the build | [Readiness checks](https://help.the-meridian.ai/deployment.md#readiness-checks) |
| `build_failed`, `BUILD_TIMEOUT` | The Docker build failed or ran out of time | [Build logs](https://help.the-meridian.ai/logs.md#build-logs) |
| `deploy_failed`, `Release command failed:` | The release command or the new revision failed | [Why a deploy fails](https://help.the-meridian.ai/deployment.md#why-a-deploy-fails) |
| `The container did not start listening on port`, `The container exited before it started listening on port` | The app crashed at boot or listens on the wrong port | [Container port](https://help.the-meridian.ai/deployment.md#container-port), [When the app crashes at boot](https://help.the-meridian.ai/logs.md#when-the-app-crashes-at-boot) |
| `healthcheck_failed` | Cloud Run didn't report the new revision ready, and the health check path didn't answer 200 | [Health checks and traffic](https://help.the-meridian.ai/deployment.md#health-checks-and-traffic) |
| `permission_denied`, `Deployment is unavailable because` | Plan, trial, suspension or hosting hold | [Why a deploy fails](https://help.the-meridian.ai/deployment.md#why-a-deploy-fails) |
| `timeout` | A step stalled and was stopped | Deploy again |
| `One or more configured secrets are missing or unavailable` | A secret the environment needs is gone | [Environment variables](https://help.the-meridian.ai/secrets.md) |
| `Your migration ... creates the Session table together with other tables` | `prisma migrate deploy` would fail with P3005 | [Why a deploy fails](https://help.the-meridian.ai/deployment.md#why-a-deploy-fails) |
| `Dockerfile not found at root of repository`, `DOCKERFILE_MISSING` | No `Dockerfile` at the repository root | [What your repository needs](https://help.the-meridian.ai/deployment.md#what-your-repository-needs) |
| `ENVIRONMENT_NOT_READY` | The environment's database is still being created | [The first deploy waits for the database](https://help.the-meridian.ai/deployment.md#the-first-deploy-waits-for-the-database) |
| `A deployment is already in progress for this environment` | One deployment at a time per environment | Follow it, then deploy again |

## Readiness checks

Returned by `meridian doctor`, `app_readiness_get` and a deploy's own checks, as each check's `code`. All are explained in [Readiness checks](https://help.the-meridian.ai/deployment.md#readiness-checks).

| Code | Means |
| - | - |
| `missing_shopify_client_id`, `missing_shopify_client_secret` | The Shopify credentials are not saved on the Meridian SDK page |
| `shopify_partner_not_connected`, `missing_shopify_app_id` | The Shopify Partner connection is missing or incomplete |
| `shopify_partner_token_rejected`, `shopify_partner_ids_not_found`, `shopify_partner_unreachable`, `shopify_partner_connection_error` | The last Shopify Partner connection attempt failed: Shopify refused the token, found no organization or app with that ID, or could not be reached. The last code means another failure, shown on the Shopify card in **App settings > Integrations** |
| `repository_not_connected`, `missing_dockerfile` | No repository, or no `Dockerfile` at its root |
| `auto_deploy_production_branch_unprotected` | Pushes deploy to production from a branch GitHub or GitLab reports as unprotected |
| `database_provisioning`, `database_failed` | The environment's database is not ready |
| `database_missing_for_prisma` | The repository has Prisma migrations and the environment has no database |
| `sqlite_provider`, `local_file_url` | Prisma doesn't point at the attached database |
| `prisma_migrations_without_release_command` | Migrations exist but nothing runs them |
| `missing_shopify_app_url`, `shopify_app_url_custom_domain`, `shopify_app_url_mismatch` | `SHOPIFY_APP_URL` is missing, points at the wrong address, or isn't `application_url` in `shopify.app.toml` |
| `scopes_mismatch` | A `SCOPES` you set doesn't match `shopify.app.toml` |
| `no_active_plans` | Plan Builder has no active plan |
| `custom_domain_not_ready` | A custom domain is not active yet |
| `datasource_not_database_url`, `session_model_missing`, `missing_shopify_app_toml`, `missing_application_url` | Only from `meridian doctor` in a repository not linked to an app: the Prisma datasource ignores `DATABASE_URL`, the schema has no `Session` model, or `shopify.app.toml` or its `application_url` is missing. See [Doctor before the app exists](https://help.the-meridian.ai/cli-reference.md#doctor-before-the-app-exists) |

## Plans and billing

| Code or message | Means | Fix |
| - | - | - |
| `SHOPIFY_BILLING_NOT_READY` | The app can't charge through Shopify yet | [Paid plans need Shopify billing set up](https://help.the-meridian.ai/publishing-plans.md#paid-plans-need-shopify-billing-set-up), [Shopify billing is not set up](https://help.the-meridian.ai/sdk-errors.md#shopify-billing-is-not-set-up) |
| `PLAN_BUILDER_UNAVAILABLE` | Meridian can't read the app's Shopify session store | [What the session store can block](https://help.the-meridian.ai/publishing-plans.md#what-the-session-store-can-block) |
| `PLAN_LOCKED` | Subscribers would pay more: save a new version | [Meridian MCP troubleshooting](https://help.the-meridian.ai/mcp-server.md#troubleshooting) |
| `PLAN_NOT_LATEST_VERSION` | A newer version of the plan exists | [Meridian MCP troubleshooting](https://help.the-meridian.ai/mcp-server.md#troubleshooting) |
| `PLAN_VALIDATION_ERROR` | The plan breaks a rule the message names | [Meridian MCP troubleshooting](https://help.the-meridian.ai/mcp-server.md#troubleshooting) |
| `USAGE_VIEW_PLAN_LOCKED` | A plan prices a view of this event | [Meridian MCP troubleshooting](https://help.the-meridian.ai/mcp-server.md#troubleshooting) |
| `Plan not found` on subscribe | `planId` is a handle or an old version | [useMeridian actions](https://help.the-meridian.ai/sdk-use-meridian.md#actions) |

## Meridian MCP

| Message | Means | Fix |
| - | - | - |
| `App not found, or you do not have access to it.` | Wrong `app_id`, or a permission your role lacks | [Plan requirements](https://help.the-meridian.ai/mcp-server.md#plan-requirements) |
| `This app's Meridian plan does not include the ... feature.` | The app's plan lacks that feature | [Plan requirements](https://help.the-meridian.ai/mcp-server.md#plan-requirements) |
| `This feature is only available for public applications.` | Plan Builder and Grow tools need a public app | [App types](https://help.the-meridian.ai/app-types.md) |
| `... requires two-factor authentication.` | The organization enforces 2FA | [2FA](https://help.the-meridian.ai/2-fa.md) |
| `Demo mode is on.` | Writes are off in demo mode | [Demo mode](https://help.the-meridian.ai/demo-mode.md) |
| `Refusing because confirm: true was not supplied` | The tool needs your decision | Call again with `confirm: true` once you decide |
| `Use x_y instead of xY` | Arguments are snake\_case | [Meridian MCP troubleshooting](https://help.the-meridian.ai/mcp-server.md#troubleshooting) |
| `Unknown status` (`webhook_deliveries_list`) | A status that doesn't exist | [Delivery statuses](https://help.the-meridian.ai/mcp-server.md#delivery-statuses) |
| `Too many deploy, rollback, database reset or variable write calls.` | 10 such calls a minute | Wait and retry |

## CLI

The CLI's exit codes and JSON error shape are in [Errors and exit codes](https://help.the-meridian.ai/cli-reference.md#errors-and-exit-codes).

| Message | Means | Fix |
| - | - | - |
| `You are not logged in to Meridian.`, `Your Meridian CLI token has expired.` | No valid sign-in on this machine | `meridian login`. See [Signing in](https://help.the-meridian.ai/cli-auth.md) |
| `This project is not linked to a Meridian app.` | No `.meridian/project.json` | [Linking a project](https://help.the-meridian.ai/cli-auth.md#linking-a-project) |
| `Cannot prompt for ... in a non-interactive shell.` | A question needs a flag in scripts | [From a script or an agent](https://help.the-meridian.ai/cli-dev.md#from-a-script-or-an-agent) |
| ``sets `provider = "sqlite"`, but the managed developer database is MySQL or PostgreSQL`` | The template's SQLite datasource | [Prepare Prisma](https://help.the-meridian.ai/cli-dev.md#prepare-prisma-once) |
| `so this command would not touch the managed developer database` | The datasource doesn't read `DATABASE_URL` | [Prepare Prisma](https://help.the-meridian.ai/cli-dev.md#prepare-prisma-once) |
| `declares no shadowDatabaseUrl` | `prisma migrate dev` needs a shadow database | [Prepare Prisma](https://help.the-meridian.ai/cli-dev.md#prepare-prisma-once) |
| `was written for a different database engine and cannot apply to MySQL` | A SQLite or PostgreSQL migration history | [Prepare Prisma](https://help.the-meridian.ai/cli-dev.md#prepare-prisma-once) |
| `dev_database_limit_reached` | The plan's developer databases are used up | [When the developer database is not there](https://help.the-meridian.ai/cli-dev.md#when-the-developer-database-is-not-there) |
| `dev_database_over_storage_limit` | Over the 25 MB limit | [When the developer database is not there](https://help.the-meridian.ai/cli-dev.md#when-the-developer-database-is-not-there) |
| `Timed out waiting for the developer database to be provisioned.` | The first provisioning took more than five minutes | Run `meridian dev` again |
| `Port <port> is already in use.` | Another process holds that port | [Running your app](https://help.the-meridian.ai/cli-dev.md) |
| `meridian dev is already running for this app` | One `meridian dev` per app | [Running your app](https://help.the-meridian.ai/cli-dev.md) |
| `Commit ... is not on any pushed branch.` | `meridian deploy` builds pushed commits only | `git push`, then deploy again |
| `cli_upgrade_required` | The CLI is too old | [Upgrading the CLI](https://help.the-meridian.ai/cli-reference.md#upgrading-the-cli) |

## Webhooks

| Code or message | Means | Fix |
| - | - | - |
| A forward answered 401 or 403 | Your route didn't verify Meridian's signature | [Retries and permanent failures](https://help.the-meridian.ai/pub-sub.md#retries-and-permanent-failures) |
| A forward answered 404, 405 or 410 | No route at the forward path | [Retries and permanent failures](https://help.the-meridian.ai/pub-sub.md#retries-and-permanent-failures) |
| `Forwarding disabled for this topic.` | The topic has no forward path | [Delivery statuses](https://help.the-meridian.ai/mcp-server.md#delivery-statuses) |
| `No app runtime target resolved for webhook.` | No deployed environment to forward to | [Where forwards go](https://help.the-meridian.ai/pub-sub.md#where-forwards-go) |
| No delivery at all | Not routed, not registered, or declared in `shopify.app.toml` | [Deliveries](https://help.the-meridian.ai/pub-sub.md#deliveries) |

## SDK

The SDK's error codes (`MeridianApiError`), what degrades and what throws, are in [Errors and degradation](https://help.the-meridian.ai/sdk-errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.