---
title: Troubleshoot failed deployments
description: 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.
url: https://agentlab.cresclab.com/docs/en/deploy/troubleshooting
language: en
updated: 2026-10-06
---

# 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.

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](https://agentlab.cresclab.com/docs/en/deploy/runtime-contract.md#writable-paths).

## 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.