---
title: Troubleshooting
description: Fix common build failures and unhealthy deployments.
order: 0
---

Most deployment problems fall into a few categories. Start with the [build logs](/docs/observability/build-logs.md) and [runtime logs](/docs/observability/runtime-logs.md) 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](/docs/guides/monorepos.md). Confirm the **root directory** and **Dockerfile path** in [project settings](/docs/guides/configuration.md) 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](/docs/guides/build-machines.md).

### Missing build dependency or token

If a build step needs a private registry token or build flag, add it as a **build** [environment variable](/docs/guides/environment-variables.md). Runtime variables are not available during the build.

### Auto-detected build fails

If you don't have a Dockerfile and [automatic detection](/docs/guides/supported-frameworks.md) 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](/docs/guides/container-requirements.md).

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

```javascript
app.listen(3000, "0.0.0.0");
```

### `/` 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](/docs/guides/redeploys.md) to apply them.

### Wrong branch deploying

Deployments trigger on pushes to the project's **default branch**. Update it in [project settings](/docs/guides/configuration.md) 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](/docs/networking/dns-configuration.md) 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](/docs/networking/custom-domains.md).

## Deployments blocked

If you can't deploy at all, confirm your workspace has an [active subscription](/docs/billing/managing-billing.md). 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](/docs/guides/container-requirements.md): the runtime contract.
- [Build logs](/docs/observability/build-logs.md) and [Runtime logs](/docs/observability/runtime-logs.md).
- [FAQ](/docs/resources/faq.md): common questions.