When the AI says your deploy failed

Your assistant says the deploy failed. What happens next depends on where it stopped.

A missing key needs a value from you. A build error may need a change in your project. A daily limit needs a decision. Check which failure you have before publishing again.

Percher's CLI and MCP tools return a structured next step alongside the explanation. That recovery object tells your assistant whether to inspect the failure, change a file, ask for a setting or stop and ask you. Connection failures and rejected tool arguments can happen before a recovery is available. The agent recovery contract explains how the assistant is instructed to handle those results.

Here is how that works for four kinds of deploy failure.

A required key is missing

REQUIRED_ENV_MISSING means Percher found a required environment key without a saved value. The check covers keys declared in your app's configuration and keys discovered during earlier builds. It runs before the build is queued.

The recovery names the missing keys and sets nextAction to set_env_vars. If OPENAI_API_KEY is missing, your assistant needs the value from you. It cannot infer a secret from the code. You can enter it under the app's private settings in the dashboard. The MCP tool for setting values is percher_env_set.

Once the value is saved, publish again. Keep secrets out of your source files and percher.toml.

The build failed

BUILD_FAILED covers failures while building the app. It can be an install error, a missing script or a compiler error. It does not always mean your code failed to compile.

When Percher can identify a problem in a file, the recovery can point your assistant straight to it. Otherwise, the local MCP server can suggest percher_doctor in deploy mode. Doctor reads the failed deploy's build log and looks for recognised patterns. It may find a missing dependency, an environment key or a source location. If it cannot narrow the cause down, the next step is to inspect the build log.

The hosted connector uses percher_deploys_inspect for build-log inspection. It does not expose Doctor. Your assistant's available tools depend on which connection you use.

Doctor does not edit your files or publish a fix. Your assistant does that separately, after inspecting the result. A recognised error is a starting point, not proof that the suggested change will solve it.

The build passed, but the app did not become healthy

The image built, but the app did not pass its startup health check. The timeout is configurable, so it is not always 30 seconds.

Before removing the failed container, Percher tries to append its health state and the last 50 lines of output to the deploy log. This capture is best effort and covers the first failed instance. If the container or worker cannot be reached, those details may be unavailable.

Check the configured port and health path first. Then read the startup output. The app may have exited because a setting was missing or a database was unreachable. A platform or worker failure can also interrupt the check, so a timeout alone does not prove the fault is in your code.

Ask your assistant to inspect the failed deploy before trying again. The troubleshooting guide covers the checks you can make yourself.

The daily deploy limit was reached

DAILY_QUOTA_EXCEEDED means the account has reached the limit for that kind of deploy. Live deploys and previews have separate counters. Limits depend on the account's plan; counters reset at midnight UTC.

The recovery uses ask_user and marks the failure as not retryable. Your assistant should show you the limit and wait for your decision. Repeating the same request will not get past it.

You can wait for the reset. A preview may still be available if its own counter has room, but it shares the app's PocketBase and /app/data with the live version. It is not an isolated copy of your data.

If the app crashes after publishing

Open the app's Health page for its crash report and Logs for the output. Reports recognise common causes, including missing packages, syntax errors, unavailable databases and memory exhaustion. Unrecognised crashes still need investigation.

You can also run Doctor from a terminal. Replace my-app with your app's name:

bunx percher doctor --app my-app --mode runtime

Run bunx percher login first if you are not signed in. The local MCP server exposes the same runtime checks through percher_doctor. The hosted connector cannot read runtime logs or crash reports; use the dashboard for those.

The crash diagnostics guide explains what each report contains. If the cause is still unclear, keep the deploy ID and the relevant error when you contact support.