Troubleshoot deployments

Start with the first specific failure message near the end of the deployment output. Later messages are often consequences rather than the cause.

A reliable troubleshooting sequence

1. Confirm the workspace, project, application, and newest deployment.
2. Read the deployment state and latest meaningful error.
3. Compare the failing release with the last known-good source and configuration.
4. Change one likely cause.
5. Save or deploy once, then observe the new deployment.
6. If the problem persists, collect non-secret evidence for support.

Source problems

Repository cannot be read

Verify the repository URL, connected GitHub account, workspace, and repository permission. Refresh the repository list after changing GitHub access.

Branch or root directory is wrong

Confirm exact spelling and capitalization. For a monorepo, make sure the root directory contains the application’s build files.

Image cannot be pulled

Verify the registry, repository, and tag. Confirm the tag exists and that authorized access is available. Do not include a registry credential in the image URL or support request.

Build problems

Command not found or dependency installation fails

Check the selected runtime and the build command. Use the project’s supported package or dependency files and reproduce the command in your normal development workflow.

Static output directory is missing

Run the build and note the directory it creates. Enter that directory relative to the configured root directory.

Startup problems

Web service is not reachable

Confirm that:

• the start command keeps running;
• the app listens on the configured port;
• required environment values are present;
• startup does not depend on a missing file or volume;
• the process does not exit immediately.

Worker exits immediately

A worker should normally remain running. Check its start command and logs. If it is designed to run once and exit, confirm that this workload shape matches what the current platform supports.

Resource problems

If startup is slow, the process is terminated, or work fails under load, compare the application’s CPU and memory allocation with its real needs and the remaining pool capacity. Review logs before increasing resources; a configuration error can look like a capacity problem.

Runtime-data problems

Check environment variable names for spelling and case. Confirm mount paths and expected file permissions from the application’s point of view. Never print a secret to confirm it exists; log only a safe boolean or redacted diagnostic.

What to send support

Safe, useful details include:

• workspace, project, and application names when they contain no sensitive data;
• deployment ID and approximate timestamp;
• customer-facing status and redacted error text;
• source type and non-secret repository or image reference;
• the troubleshooting steps already attempted.

Do not send passwords, tokens, private keys, environment values, MFA setup keys, full unreviewed logs, or customer records.