Configure

Troubleshooting

Find the message from your build log, deploy log or browser below. Every entry says why it happens and how to fix it. Start by reading the first lines of the build log — they say how your repository was detected, which explains most surprises.

Getting the code#

This workspace has no GitHub connection for this repository. Connect GitHub in the workspace settings, then build again.

Builds, and especially automatic deploys on push, read your code through the workspace's GitHub connection. An Owner or Admin opens GitHub in the sidebar and connects the GitHub account or organisation that owns the repository. Everyone in the workspace then uses it; nobody connects GitHub individually.

Branch "main" doesn't exist in owner/repo (its default branch is "master")

The service is set to a branch the repository doesn't have. Open the service → Settings: the Branch list shows the repository's real branches and picks its default. Choose the right one and press Save and redeploy.

GitHub doesn't show owner/repo through this connection

The workspace's GitHub connection can't see that repository. Check the repository address on the service's Settings tab. If it's right, the repository isn't included in the app's access: on GitHub, the organisation (or account) → Settings → GitHub Apps → Atom Code Connect → Configure → Repository access, then add the repository, or choose All repositories. An organisation owner has to do this.

GitHub rejected the connection's credentials. Reconnect GitHub and try again.

The workspace's GitHub connection was removed or suspended on GitHub. An Owner or Admin reconnects it from GitHub in the sidebar.

Could not parse a GitHub owner/repo from "…"

Use the repository's web address: https://github.com/owner/repo — not an SSH URL or a link to a file.

Build failures#

docker-compose.yml can't be deployed as a Container App: services.backend.volumes: bind mount of "…/backend" is not allowed — use a named volume

Your Compose file is a development one — it mounts source folders into containers. Keep it, and add a docker-compose.prod.yml without the bind mounts; production file names are picked first. How.

JWT_SECRET is required (or any ${NAME:?…} message)

The Compose file marks a variable as required and it isn't set. Add it in the service's Environment tab, then Builds → Trigger build.

Environment variables not referenced in docker-compose.prod.yml (containers won't see them): …

A warning, not an error. Those dashboard variables reach no container, because no service lists them in its environment as NAME: ${NAME}. Details.

Several services declare ports (…), so none is made public automatically — label the public one with crowther.public: "true"

Add crowther.public: "true" to the labels of the service that should get the address. How it's chosen.

Service "…" is labelled crowther.public but has no port — add a "crowther.port" label, ports or expose

Say which port that service listens on: crowther.port: "80", or an expose entry.

COPY failed: file not found / npm ERR! enoent / no such file or directory

The build context is the repository root (or the Compose build.context). Paths in COPY are relative to it, and anything in .dockerignore is invisible. Also check the file is actually committed — builds use what is on GitHub, not your local folder.

Railpack detects no language, or reports it found no start command

Nothing it recognises is at the repository root — often the code is in a sub-folder. Move it up, add a Dockerfile at the root, or use a root Compose file pointing into the folder (monorepos).

… timed out after 45 minutes (BUILD_STEP_TIMEOUT_MS)

Builds have a 45-minute limit. Use a multi-stage Dockerfile, a .dockerignore, and install dependencies before copying source so the dependency layer is reused.

exec format error

An image built for the wrong CPU (usually arm64 from an Apple Silicon Mac) is referenced with image:. Let the platform build it from source instead — it always builds linux/amd64.

Deploy failures#

container … is unhealthy / dependency failed to start

A container's healthcheck never passed. Check that the command works inside that image (curl is missing from many images — use wget or python -c), that it targets the port the process really uses, and that start_period is long enough for start-up work such as migrations.

Health check failed for replica 0

The dashboard's Health-check path is set. Clear it in Settings — use a HEALTHCHECK in your Dockerfile instead (why).

Bind for 0.0.0.0:3000 failed: port is already allocated

Same cause: a health-check path makes the service claim its port on the server, and another service or replica already has it. Clear the health-check path.

Scheduling failed: INSUFFICIENT_CAPACITY — No node has enough free capacity

The servers are full for the resources this service asks for. Tell the platform team; lowering the service's replicas may also help.

Container exits immediately / restarts in a loop

The process crashed on start — most often a missing environment variable, or a start command pointing at a file that doesn't exist in the image. Run the image locally with the same variables to see the error.

In the browser#

502 Bad Gateway

The router reached the server but not your app. In order of likelihood:

  • Wrong port. A Web service must listen on 3000. Set PORT=3000 — Python frameworks otherwise use 8000.
  • Listening on localhost. Bind to 0.0.0.0.
  • A single-page app deployed as a Web service. Redeploy it as a Static site.
  • Container App: wrong public port. crowther.port must be the port the public service listens on inside its container.

404 page not found (plain text, not your app's 404)

No app is routed at that address: the deploy failed, the service was renamed (its address changed), or a Container App has no public service. Check the latest deployment and the address on the Domains tab.

Static site loads a blank page, or refreshing a route gives 404

Open the browser console. Usually the app calls an API URL it didn't get at build time — build-time values. With a custom Dockerfile, make sure unknown paths fall back to index.html.

Blocked by CORS policy

Add the frontend's full address (https://…cloud.crowtherlabs.com and any custom domain) to the backend's allowed origins, then Redeploy the backend. Serving both on one address avoids CORS entirely.

NET::ERR_CERT_… on a custom domain

The domain's certificate isn't issued yet — see its status on the Domains tab and DNS mistakes that stop the certificate.

My change isn't live

A push to the service's branch deploys automatically, so first look at the Builds tab: the build may still be running, or it may have failed (the log says why, and you'll have had an email). If no build started at all, work through My push didn't deploy.

After changing only environment variables, press Deployments → Redeploy: variables don't reach a running app until it restarts.

Uploaded files disappeared after a deploy

Single services have no persistent disk. Use object storage, or a Container App with a named volume.

Still stuck?#

Send the platform team:

  • the service name and the link to the failing build or deployment,
  • the first 20 and last 20 lines of its log,
  • what you changed since it last worked.

Never paste secrets

Remove passwords, tokens and keys from anything you share — including screenshots of the Environment tab.

Test locally before asking

Most build and start-up problems reproduce with docker build / docker compose up --build on your own machine, where they are much faster to fix.