Troubleshooting

Most deployment problems fall into a few categories. Start with the build logs and runtime logs for the failing deployment, then match the symptom below.

# Build failures

# Build can't find the Dockerfile

The Dockerfile path is resolved relative to the project's root directory. Confirm the root directory and Dockerfile path in project settings point at the right location. For a monorepo, the root directory should be the app's subdirectory.

# Build runs out of memory or times out

Heavy compilation (large Node or Rust builds, big dependency trees) can exhaust the build machine. Move to a larger build machine tier.

# Missing build dependency or token

If a build step needs a private registry token or build flag, add it as a build environment variable. Runtime variables are not available during the build.

# Auto-detected build fails

If you don't have a Dockerfile and automatic detection can't build your app, add a Dockerfile for full control over the build and start command.

# Unhealthy deployments

A deployment that builds successfully but never becomes healthy is failing its health check.

# Not listening on port 3000

Your app must listen on port 3000 and bind to 0.0.0.0, not 127.0.0.1. Binding to localhost prevents Atlasflow from reaching it.

# / doesn't return 2xx

The health check is GET /. If your app returns 404 on /, or redirects to a login page that returns 302, health checks fail. Make sure / returns a 2xx status.

# Configuration issues

# Environment variable not present

Confirm the variable is in the right scope: runtime values are injected into the running container, build values are only available during the build. After changing variables, trigger a redeploy to apply them.

# Wrong branch deploying

Deployments trigger on pushes to the project's default branch. Update it in project settings if needed.

# Domain issues

# Domain stuck on "verifying"

DNS can take time to propagate. Confirm both the routing record (A or CNAME) and the TXT ownership record match the exact values shown in the dashboard, then re-check verification.

# "Domain already in use"

A verified domain can only attach to one project. Remove it from the other project first. See Custom domains.

# Deployments blocked

If you can't deploy at all, confirm your workspace has an active subscription. Deployments require one.

# Still stuck?

Gather the deployment's build and runtime logs and submit feedback from the dashboard with a description of the problem.

# Related

• Container requirements: the runtime contract.
• Build logs and Runtime logs.
• FAQ: common questions.