Troubleshooting

Most deployment failures are one of four things: the image did not build, the container listened on the wrong port, the health check failed, or DNS is still pointing at the wrong place.

Fast Check

Start with the deployment log stream. If Hatch says the app is live but the URL fails, check the hostname and the response from the load balancer directly.

triage.sh

curl -i https://<subdomain>.hatchcloud.xyz
nslookup <subdomain>.hatchcloud.xyz
docker build -t hatch-debug .
docker run --rm -p 8080:<container-port> hatch-debug

Build

docker

The image must build from the repository root and include everything needed at runtime.

Port

runtime

The project port in Hatch must match the port your container listens on.

Health Check

alb

The configured path should return a successful HTTP response after the app starts.

DNS

routing

The app hostname must resolve to the current user-app load balancer.

Symptom Map

Use this table when the deployment reached a known state but the app still does not behave as expected.

Symptom	Likely Cause	Next Step
Build failed	Dockerfile, missing lockfile, or private dependency	Run docker build locally from the repo root
Task never healthy	Wrong port, localhost bind, or bad health path	Check port, bind to 0.0.0.0, and return 200-399
No project mapped	Hostname reached the default ALB rule	Confirm DNS points at the current user-app ALB
DNS error	Record missing, stale cache, or proxied incorrectly	Compare local nslookup with 1.1.1.1
Repos missing	GitHub OAuth access changed	Sign in again and verify repo permissions

Runtime Failures

When the build and push succeed but the service never becomes healthy, check the app process before the cloud infrastructure.

Port mismatch

The container listens on 3000, but the Hatch project is configured for 80.

Localhost bind

The app binds to 127.0.0.1, so the load balancer cannot reach it.

Slow boot

The app takes longer than expected before the health check starts passing.

Bad health path

The configured health path returns 404, 500, or redirects forever.

A good default for web services is to bind to 0.0.0.0, expose one HTTP port, and keep/ or /health returning a simple success response.

DNS And Routing

If the same URL sometimes works and sometimes returns the default Hatch response, local DNS is probably still resolving to an old load balancer.

dns-check.sh

nslookup <subdomain>.hatchcloud.xyz
nslookup <subdomain>.hatchcloud.xyz 1.1.1.1
curl -i -H "Host: <subdomain>.hatchcloud.xyz" https://<alb-dns-name>/

Browser refreshes do not always clear DNS cache. When in doubt, compare your router resolver with 1.1.1.1before changing application code.