Crescendo Lab Docs
English
Sign up

Troubleshoot failed deployments

When a version fails, read the reason on its page. If the content was refused, fix it and upload again; if the platform failed, retry.

Last updated

The content was refused#

What you seeCauseFix
Can't tell how to build this sourceNo package.json, index.html or Dockerfile at the top of the zip.Zip from inside the project folder, or see deploy from source code.
The project is a service, but the upload reads as plain filesNo Dockerfile or manifest (package.json, go.mod, pyproject.toml, requirements.txt, setup.py) at the top of the zip: the project is in a subfolder, such as backend/.Set Root Directory to that folder in Settings › Build settings, and deploy again. The failure lists the folders that could be it.
No index.html foundThe folder was zipped instead of its contents.Zip from inside the folder so index.html is at the top.
A secret in the filesThe upload contains something that looks like an API key or token.Remove it, rotate the key, enter it in the project's Settings, and upload again.
The image has no CMDThe Dockerfile has no start command.Add a CMD or ENTRYPOINT.
The USER doesn't existThe Dockerfile names a user the image doesn't have.Use a numeric uid or a user the image has, such as node.
Critical vulnerabilitiesA package in the image has a known critical vulnerability.Upgrade the package to the version the finding names, or move to a newer base image that has it.

The build ran and failed#

The failure code is buildFailed: the build started, and one of its steps failed. The failure shows that step, what it printed and the exit code it ended with. In the console, read the log excerpt in the failure banner on the version's page; over MCP, read failure.buildLog in sites_deploy_status.

Exit codeCauseFix
127The build ran a command that isn't installed. For example, the build runs tsc, but typescript is in neither dependencies nor devDependencies in package.json.Add the package, or remove the command from the build command.

Fix the project and deploy again. That is a new upload: retrying the same version fails the same way.

A preview address doesn't answer#

  • A web page (static site): its preview address answers 404 site not found until its version publishes.
  • A service: a version that has never been live isn't started, so its preview address answers 502 service unavailable, with the header X-Sites-Refusal: relay-unavailable, until it goes live. That isn't a build failure.

Right after going live, open the public address. If it doesn't work, fix it and deploy again. To catch problems before visitors do, first try versions in a separate environment, such as staging.

Awaiting confirmation#

When a check set to "asks first" finds something, the version stops at Awaiting confirmation. After reading the findings, you can publish anyway. High vulnerabilities are handled this way; the fix is the same as for critical ones, and upgrading clears the warning.

The version never becomes ready#

If the build succeeded and the version is live but the Runtime tab never shows ready instances, the server is usually not listening on the port the platform gave it.

  1. Check the version page for an imagePortsAmbiguous notice.
  2. Make the server listen on the PORT environment variable, or enter the port it listens on in Settings › Runtime settings › Port.
  3. Select Restart service.

It keeps restarting#

The usual cause is a program writing outside /tmp on the read-only filesystem. Move the writes to /tmp; see the container runtime contract.

A request ends with a 504 or a stream stops#

If the 504 carries X-AgentLab-Error: platform-timeout, or a streamed response stops at the same number of seconds every time, the request reached the project's request duration. Raise it, and don't resend the request automatically; see Request duration.

The platform failed#

When the platform itself caused the failure, retry the same version. You don't need to change or upload anything.

A version no build machine picks up within an hour is queued again automatically, once, in the same place. If another hour passes, it shows Expired. Retry it the same way within a day of the upload; after that, upload it again.

If you queued a version by mistake, or don't want to wait for it, cancel it while it is still queued; see Cancel a queued build.

Still stuck#

  • On the Runtime tab, check the instances and read the recent logs.
  • On the version page, read the notices the platform left.
  • Ask an AI tool connected to Agent Lab MCP to read the deploy status for you. It sees the same codes as this page.