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.
The content was refused#
| What you see | Cause | Fix |
|---|---|---|
No index.html found | The folder was zipped instead of its contents. | Zip from inside the folder so index.html is at the top. |
| A secret in the files | The upload contains something that looks like an API key or token. | Remove it, rotate the key, enter it in the app's Settings, and upload again. |
The image has no CMD | The Dockerfile has no start command. | Add a CMD or ENTRYPOINT. |
The USER doesn't exist | The Dockerfile names a user the image doesn't have. | Use a numeric uid or a user the image has, such as node. |
| Push refused, not amd64 | The image was built as arm64 on an Apple silicon Mac. | Rebuild with docker build --platform linux/amd64. |
| Critical vulnerabilities | A 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. |
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 is what 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.
- Check the version page for an
imagePortsAmbiguousnotice. - Make the server listen on the
PORTenvironment variable, or enter the port it listens on in Settings › Runtime settings › Port. - 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.
The platform failed#
When the platform itself caused the failure, retry the same version. You don't need to change or upload anything.
Still stuck#
- On the Runtime tab, check the instances and read the recent logs.
- On the image's Check tab, 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.