Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Cloud Run says the container failed to start or the startup probe failed on port 8080

ErrorContainer failed to start. Failed to start and then listen on the port defined by the PORT environment variable.

Short answer

Cloud Run starts a TCP startup probe against your container port and shuts the instance down if nothing answers in time. The usual causes are an app bound to 127.0.0.1, an app listening on a port other than PORT, a crash before it listens, an image built for the wrong CPU, or a start that is slower than the probe window.

  • Applies to Cloud Run, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the same image on your machine with the PORT variable set the way Cloud Run sets it, then call it from the host. If it does not answer here, it will not answer on Cloud Run either.

    docker run --rm -p 8080:8080 -e PORT=8080 my-image
    curl -I http://127.0.0.1:8080
  2. 2Match what you see, then jump to its fix

    1. 1The app starts and logs no error, but nothing answers from outside the containerThe app listens on 127.0.0.1 and not on all interfacesFix
    2. 2The log shows the server started, but on a port other than 8080 or the value of PORTThe app listens on a different port than the one Cloud Run usesFix
    3. 3Application errors or a stack trace in stdout or stderr in Cloud Logging just before the failure messageThe app crashes before it starts listeningFix
    4. 4Image built on an Apple Silicon or other ARM machine; the container fails at once with no application logThe image was built for the wrong CPU architectureFix
    5. 5Logs show normal start-up messages that finish after the instance was already stoppedThe app is healthy but takes longer to start than the probe allowsFix

What does the error look like?

  • Container failed to start. Failed to start and then listen on the port defined by the PORT environment variable.
  • The user provided container failed to start and listen on port defined by PORT=8080 environment variable within the allocated timeout.

Cause 1 of 5

The app listens on 127.0.0.1 and not on all interfaces

1Check

Look at what address the server prints at start-up, or at the framework's host setting. Cloud Run needs the ingress container to listen on 0.0.0.0 and says it must not listen on 127.0.0.1.

docker run --rm -p 8080:8080 -e PORT=8080 my-image
curl -I http://127.0.0.1:8080

2Fix

Make the server bind to 0.0.0.0. For ASP.NET Core, Node.js, Flask and similar frameworks this is one host or URL setting.

// Node.js
app.listen(process.env.PORT || 8080, '0.0.0.0');

# Flask
app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))

3Verify

Rebuild, run it locally with -p 8080:8080 and call it from the host, then deploy again.

curl -I http://127.0.0.1:8080

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 2 of 5

The app listens on a different port than the one Cloud Run uses

1Check

Cloud Run puts the port it expects into the PORT environment variable (8080 by default, or the container port you configured). A hard-coded port such as 3000 or 5000 never matches unless you set the container port to it.

grep -rn "listen\|PORT" src/ | head

2Fix

Read PORT in the app, or set the service's container port to the one the app really uses.

const port = process.env.PORT || 8080;
app.listen(port, '0.0.0.0');

3Verify

Deploy and watch the revision become ready.

docker run --rm -p 8080:8080 -e PORT=8080 my-image

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 3 of 5

The app crashes before it starts listening

1Check

Cloud Run writes container stdout and stderr to Cloud Logging. Open the logs of the failed revision and read the lines before the failure message: a missing environment variable, a failed database connection or a missing file ends the process early.

docker run --rm -e PORT=8080 my-image   # compare with the revision's logs in Cloud Logging

2Fix

Fix the error the log shows. Do not run slow work (migrations, large downloads) before the server starts listening.

# reproduce locally with the same variables the service has
docker run --rm -p 8080:8080 -e PORT=8080 -e KEY=value my-image

3Verify

The new revision reports as ready and the service URL answers.

curl -I https://my-service-xxxxx-uc.a.run.app

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 4 of 5

The image was built for the wrong CPU architecture

1Check

Cloud Run needs a 64-bit Linux image, and Google notes that images built on ARM machines may not work. See which architecture your image has.

docker image inspect my-image --format '{{.Os}}/{{.Architecture}}'

2Fix

Build for linux/amd64 (or rebuild with Cloud Build) and push that image.

docker buildx build --platform linux/amd64 -t my-image .

3Verify

The inspect command prints linux/amd64; deploy that image.

docker image inspect my-image --format '{{.Os}}/{{.Architecture}}'

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 5 of 5

The app is healthy but takes longer to start than the probe allows

1Check

A new service gets a default TCP startup probe with a 240 second timeout and one try (failureThreshold 1). Your instance must listen within 4 minutes. If a start-up truly needs longer, or you configured a shorter probe, the instance is stopped first.

gcloud run services describe my-service

2Fix

Set an explicit startup probe with a longer window. The total (failureThreshold x periodSeconds) may not exceed 600 seconds.

gcloud run deploy my-service --image my-image --startup-probe httpGet.path=/healthz,httpGet.port=8080,periodSeconds=10,failureThreshold=30

3Verify

Deploy and wait for the revision to report ready.

gcloud run services describe my-service

Confirmed by docs.cloud.google.com

Did this fix it?

How do I stop it coming back?

  • Run the exact image locally with -e PORT=8080 before every deploy.
  • Bind to 0.0.0.0 and read PORT in every service, and keep that in the project template.
  • Start the server first and do slow set-up work afterwards in the background.
  • Build images for linux/amd64 in CI instead of on a laptop.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.