What Cloud Run's 'failed to start and listen on the port defined by the PORT environment variable' error means, the six causes behind it, and how to find which one hit your revision.

Cloud Run shows "The user provided container failed to start and listen on port defined by PORT=8080 environment variable within the allocated timeout" whenever its startup probe never reaches your server. A crash on line one and a server on the wrong port produce the same message.
The logs for the failed revision almost always say which one, and the causes below are in the order worth checking.
When a new revision starts, Cloud Run runs a startup probe against the container port, and by default that is a TCP probe with timeoutSeconds: 240, periodSeconds: 240 and failureThreshold: 1, per the health checks docs. If no connection succeeds in that window, the revision is marked not ready and traffic stays on the previous one. The troubleshooting guide lists the same checks this page walks through.
Open the failed revision's logs, since the service-level view mixes it with the healthy one:
gcloud run revisions list --service=api --region=europe-west1 --limit=3
gcloud logging read \
'resource.type="cloud_run_revision"
AND resource.labels.revision_name="api-00042-xog"' \
--limit=50 --format='value(textPayload)'
A stack trace or exec format error points at a crash, a line like listening on 127.0.0.1:3000 points at the bind, and a log that stops partway through initialisation points at a slow start.
Cloud Run sends traffic to the port in PORT, which is 8080 unless the service sets another container port, as the container runtime contract describes. A Node server hardcoded to 3000 never answers the probe:
// server.ts
import http from "node:http";
const port = Number(process.env.PORT ?? 8080);
http
.createServer((req, res) => res.end("ok"))
// 0.0.0.0, not 127.0.0.1 or localhost
.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));
In Go, http.ListenAndServe(":"+os.Getenv("PORT"), mux) listens on all interfaces. The opposite fix works too: gcloud run deploy api --port=3000 tells Cloud Run what the container already uses.
A server bound to localhost accepts connections from inside the container only, and the probe comes from outside it. Several dev servers default to localhost: Vite and Flask's app.run() both do, and Uvicorn needs --host 0.0.0.0. Check the startup log line for the address.
Cloud Run requires 64-bit Linux on amd64, and an image built with a plain docker build on an Apple Silicon Mac is arm64. The container fails immediately with exec format error, which then shows up as this error. Build with docker buildx build --platform linux/amd64 or in Cloud Build.
The most common crash is a missing environment variable or secret: the code reads DATABASE_URL, gets an empty string and throws before it listens. Other usual suspects are a migration that runs at boot and fails, a database connection attempted before listening with no timeout, and an ENTRYPOINT that points at a file not copied into the image. Reproduce it locally with the same environment:
docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 \
europe-west1-docker.pkg.dev/my-project/apps/api:abc123
A JVM app loading a large classpath, or a service that downloads a model or warms a cache before listening, can take longer than the probe allows. Start listening first and load in the background, or turn on startup CPU boost with --cpu-boost. If the app needs more time, an HTTP startup probe with failureThreshold: 10 and periodSeconds: 30 gives a longer window, with a /healthz route that returns 200 once ready.
Encore is a backend framework with built-in infrastructure, and most of the causes above come from the gap between the app and its container. Encore builds the image itself, on the same code path encore build docker uses, and the runtime reads PORT and listens on it, so the port and bind address are never something you configure. Deploying to GCP runs your services on Cloud Run in your own project, per the GCP infrastructure docs.

Run in your terminal to get started locally.
The missing-variable crash goes away for the same reason, since a secret is declared in code and its value set per environment with encore secret set, and the database connection comes from the database declaration instead of a hand-copied DATABASE_URL:
// catalog/catalog.ts
import { api, APIError } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { secret } from "encore.dev/config";
// Provisioned as Cloud SQL on GCP; no connection string to set.
const db = new SQLDatabase("catalog", { migrations: "./migrations" });
// Set per environment with: encore secret set --type prod PricingApiKey
const pricingApiKey = secret("PricingApiKey");
interface Product {
sku: string;
name: string;
priceCents: number;
}
export const get = api(
{ expose: true, method: "GET", path: "/products/:sku" },
async ({ sku }: { sku: string }): Promise<Product> => {
const row = await db.queryRow<{ sku: string; name: string; price_cents: number }>`
SELECT sku, name, price_cents FROM products WHERE sku = ${sku}`;
if (!row) throw APIError.notFound("product not found");
return { sku: row.sku, name: row.name, priceCents: row.price_cents };
},
);
export const refreshPrice = api(
{ expose: false, method: "POST", path: "/products/:sku/refresh" },
async ({ sku }: { sku: string }): Promise<{ status: number }> => {
// The secret is read when the request needs it, not at boot.
const res = await fetch(`https://pricing.example.com/v1/prices/${sku}`, {
headers: { authorization: `Bearer ${pricingApiKey()}` },
});
return { status: res.status };
},
);
-- catalog/migrations/1_init.up.sql
CREATE TABLE products (
sku TEXT PRIMARY KEY,
name TEXT NOT NULL,
price_cents INTEGER NOT NULL
);
Migrations are applied as part of the deploy rather than when a container boots, and per the databases docs a migration that fails is rolled back and the deployment aborted, instead of leaving a revision that never answers its probe.
An AI coding agent that adds a secret or a database writes the declaration in the same change and runs the app with encore run locally, and the deploy wires the value and connection on Cloud Run without anyone editing the service's environment.
Best fit: Teams on Cloud Run who want the port, image and configuration handled so revisions fail at build or deploy time instead of at startup.
exec format error or the listen address.PORT and listen on 0.0.0.0.linux/amd64.docker run -e PORT=8080, with the same environment variables.listen, or extend the startup probe.Cloud Run started your container but never got a TCP connection on the port in the PORT environment variable before the startup probe ran out of time. The process crashed, listened on a different port or interface, or took longer to start than the probe allows.
Cloud Run uses 8080 by default and sets the PORT environment variable to the configured container port, and your server should read PORT instead of hardcoding a value, and listen on 0.0.0.0.
With the default TCP startup probe, 240 seconds: timeoutSeconds 240, periodSeconds 240 and failureThreshold 1. You can configure a TCP or HTTP startup probe with a longer total window by raising failureThreshold and periodSeconds.
Common reasons are an image built for ARM on an Apple Silicon Mac, environment variables or secrets that exist locally but not on the service, and a server bound to localhost. Run the image locally with docker run -e PORT=8080 and --platform linux/amd64 to reproduce what Cloud Run does.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.