App Engine deploy failed: invalid app.yaml (runtime not supported / entrypoint / handlers)

gcloud app deploy rejects the configuration or the app fails its health check after deploy.

Exact message you may see ERROR: (gcloud.app.deploy) Error Response: [9] Cloud build failedThe specified runtime is not supportedError Response: [3] The runtime is not supported or is invalidApp Engine entrypoint requiredYour app may not have started successfully on App Engine
Seen on: Google Cloud Python

Meaning

Use a supported runtime (runtime: python312/nodejs20), define entrypoint for runtimes that need one (gunicorn/Node start), listen on $PORT, fix handler/static file paths, and check the App Engine default service account and enabled APIs. Read build logs in Cloud Build.

Common causes

  • Unsupported/removed runtime
  • Missing entrypoint
  • App not listening on $PORT
  • Wrong static handler path
  • App Engine API/billing not enabled

⚡ Quick fix

  1. Set a current runtime and entrypoint
  2. Listen on 0.0.0.0:$PORT
  3. Check logs with gcloud app logs tail

Detailed fix by platform

YAML

  1. bash
    runtime: python312
    entrypoint: gunicorn -b :$PORT main:app

How to diagnose

  1. Runtime — Supported?
  2. Entrypoint — Defined?
  3. Port — $PORT?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):

backend spec — Firebase deploy: User code failed to load. Cannot determine backend specification (Google Cloud / Firebase)backend speccache — Firebase Hosting serves old files after deploy (CDN cache and Cache-Control headers) (Google Cloud / Firebase)cacheCannot find module — Cloud Functions: Error: Cannot find module 'X' (dependency missing at runtime) (Google Cloud / Firebase)Cannot find moduleCloud Functions: Build failed — Cloud Functions: Build failed: function.js does not exist / npm install failed with exit code 1 (Cloud Build step) (Google Cloud / Firebase)Cloud Functions: Buil…Container failed to start — Cloud Run: The user-provided container failed to start and listen on the port defined provided by the PORT=8080 environment variable (Google Cloud / Firebase)Container failed to s…deploy — Firebase Functions deploy failed: Node runtime/engine unsupported or build error (Google Cloud / Firebase)deployhosting — Firebase Hosting deploy: Could not find site / hosting target not configured (Google Cloud / Firebase)hostingModuleNotFoundError — Cloud Functions Python: ModuleNotFoundError: No module named 'X' (requirements.txt) (Google Cloud / Firebase)ModuleNotFoundErrorApp Engine

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.