Deploying applications to Google Cloud Run can often feel smooth, but every now and then, something comes up that throws a wrench in your deployment. One of the more puzzling errors I encountered recently was:
“Revision ‘[revision-name]’ is not ready and cannot serve traffic. The user-provided container failed to start and listen on the port defined by the PORT=8080 environment variable within the allocated timeout.”
In this post, I’ll share the steps I took to troubleshoot this error, what I learned about how Google Cloud Run handles container startups, and how you can make sure your container starts reliably.
The Error Breakdown
This error essentially points to two possible issues:
- Port Misconfiguration: The application isn’t listening on the expected port, which, for Cloud Run, is set by default to
PORT=8080. - Timeout Exceeded: The container didn’t start within the default time limit, causing Cloud Run to terminate the attempt.
I’ll walk through the steps I used to investigate and fix these issues.
Step 1: Ensure Your App Listens on the Right Port
The most common cause of this error is that the application simply isn’t listening on the port Cloud Run expects. Cloud Run relies on the PORT environment variable to determine which port to route requests to inside the container, and the default is 8080. Check your application code to confirm it’s listening on process.env.PORT:
For a Node.js application, it should look something like this:
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
});If your app is hard-coded to listen on a different port (e.g., 3000), it won’t connect with Cloud Run’s requests, causing the startup to fail.
Step 2: Increase the Startup Timeout
By default, Cloud Run gives your container 4 minutes to initialize and start listening on the designated port. If your application takes longer, you’ll need to increase this timeout.
Here’s how to extend the timeout using the gcloud command:
gcloud run deploy [SERVICE_NAME] --timeout=10m --other-flags...This command sets the timeout to 10 minutes, which should accommodate applications that need more time to initialize, such as those with intensive setup routines or larger libraries to load.
Step 3: Review Your Dockerfile Configuration
Your Dockerfile should expose the correct port to allow Cloud Run to access it:
EXPOSE 8080Adding this line signals to Cloud Run that your container will listen on port 8080. If you’re using another port, make sure both your Dockerfile and application code reflect this consistently.
Additionally, take a close look at the build steps in your Dockerfile. Ensure that all dependencies are properly installed, and there aren’t any unnecessary commands running during startup that could delay your container.
Step 4: Check Logs for Detailed Errors
When Cloud Run fails to start, it typically logs an error message that can provide insight into the problem. To check the logs, use:
gcloud logs read --service=[SERVICE_NAME]Look for errors or warnings related to configuration issues, dependency failures, or other potential causes. The logs are often where I find the exact reason behind a deployment failure, especially when it comes to missing dependencies or network issues.
Step 5: Configure Health Checks (if applicable)
Health checks are another factor that can influence whether your container is marked as “healthy” and ready to receive traffic. If you’ve set up custom health checks, make sure they’re not timing out too quickly or have overly strict thresholds.
You can adjust the health check parameters within Cloud Run settings if needed. This is especially important if your app has long initialization times that could cause it to fail a health check prematurely.
Wrapping Up
After making sure that your app listens on the correct port, extending the timeout, verifying your Dockerfile, checking logs, and configuring health checks, your app should now start up smoothly on Cloud Run.
These steps saved me a lot of time and frustration, and I hope they do the same for you. If you’re new to Cloud Run or just want to make sure your deployments are smooth, keep these troubleshooting tips handy. Happy deploying!
Final Thoughts
Cloud Run’s simplicity and power make it an excellent choice for deploying containerized applications, but like any cloud platform, it comes with its own set of quirks and best practices. By following these troubleshooting steps, you’ll be able to resolve many of the common startup issues that arise when deploying to Cloud Run.