What the port 8080 error means
Cloud Functions 2nd gen runs on Cloud Run infrastructure. During startup, the container must start an application server that listens on the port provided through the PORT environment variable. If the platform does not detect a listener before its startup timeout, deployment or startup can fail with a message such as “failed to listen on PORT 8080 within timeout”.
The message points to a startup and listening problem, but does not identify its cause. The application may have crashed before starting the server, may be running the wrong entry point, or may be listening on a different port or interface. Treat the logs as the next source of evidence rather than assuming the port itself is the only issue.
Start with the function type
A Cloud Functions function and a custom Cloud Run container do not necessarily have the same startup code. In a function deployment, the platform and its functions framework provide the serving process. In a custom container, your application is responsible for starting a web server that listens on the assigned port.
Before changing code, confirm how the service was deployed and which entry point or container command it uses. Do not add a standalone server just because the error mentions port 8080: doing so in a function that expects a registered function handler can create a different startup problem.
Likely causes to check
- The process exits before listening. A syntax error, missing module, invalid configuration, or exception during module loading can stop Node.js before the server starts.
- The wrong startup command or entry point is configured. The deployed command may point to another file, or the expected function handler may not be exported or registered as intended.
- The server ignores
PORT. Hard-coding a port can make the application listen somewhere other than the port assigned at runtime. - The server binds to an unsuitable interface. A server bound only to the loopback interface may not be reachable by the container platform. For a custom HTTP server, bind to
0.0.0.0. - Startup waits on unrelated work. A database connection, remote API request, or other initialization task can block or fail before the server begins listening.
- Deployment files or dependencies differ from local files. A missing file, incomplete deployment, or dependency that is unavailable in the deployed environment can cause an early failure.
These are diagnostic possibilities, not a claim about the cause of any particular deployment. Look for the first error in the startup logs; the final port message can be a consequence of an earlier crash.
Minimal example for a custom Node.js container
The following is an example of a basic HTTP server for a custom container. It is not a replacement for a Cloud Functions handler. Save it as server.js and configure the container’s startup command to run that file.
const http = require('node:http');
const port = Number(process.env.PORT || 8080);
const server = http.createServer((request, response) => {
response.writeHead(200, { 'content-type': 'text/plain' });
response.end('Service is running\n');
});
server.listen(port, '0.0.0.0', () => {
console.log(`HTTP server listening on port ${port}`);
});This example uses Node.js built-in modules and the node: module specifier. Check the Node.js documentation for the runtime version selected by your deployment before relying on version-specific APIs or syntax. The example illustrates the expected listening pattern; it is not a tested deployment recipe.
For a Cloud Functions deployment, use the function signature and entry-point configuration required by the runtime and framework you selected. Check that the configured function name matches the exported or registered handler. Do not assume the custom-container example is the right fix for a function deployment.
Diagnostic path
-
Identify the deployed artifact and startup configuration.
Confirm whether you deployed a function or a custom container. Check the selected function entry point, container command, and any build configuration. Make sure the deployed revision is using the files and settings you expect.
-
Read startup logs from the affected revision.
Find the earliest Node.js error, not only the final message about port 8080. Look for module resolution failures, syntax errors, missing environment variables, permission errors, and exceptions during initialization. If there is no useful application log, add a temporary log near the beginning of startup and redeploy.
-
Check whether the process reaches server startup.
For a custom server, log immediately before calling
listenand in its listening callback. If the first log appears but the listening log does not, investigate errors around port binding or code that prevents the callback from completing. If neither appears, verify that the intended file is actually being run. -
Use the assigned port.
Read
process.env.PORTat runtime instead of relying on a local development port. Avoid treating 8080 as a universal hard-coded value: it is the port named in this error, while the application should use the port supplied to its container. -
Check the bind address for custom containers.
For the plain Node.js example, the server binds to
0.0.0.0. Check your web framework’s current documentation for how it accepts a host and port; do not assume that every framework uses the same options or defaults. -
Temporarily simplify startup.
For diagnosis, reduce the app to a server that responds without connecting to databases or calling other services. If the small server starts, add initialization steps back one at a time. Ensure that a failed dependency does not silently prevent the server from starting.
-
Redeploy and inspect the new revision.
After making one focused change, deploy again and check the logs for that new revision. A successful local run is useful, but it does not by itself verify that the deployed command, environment, and files are correct.
Verify the fix
First confirm that the new revision completes startup and that its logs show the application reaching its listening state. Then send a request to the deployed service or function using its intended route. Check that the response comes from the new revision and that logs do not show a fresh startup crash.
If the service starts but requests fail, investigate routing, handler behavior, and application dependencies separately. A listening port confirms that a server started; it does not prove every route or downstream service is working.
Common follow-up questions
Should I always set the port to 8080?
No. For a custom container, use the runtime-provided PORT value. A local fallback such as 8080 can be convenient for development, but it should not replace reading the deployed environment variable.
Should I increase the startup timeout?
Not as the first step. A longer timeout will not fix a crashed process, a wrong entry point, or a server listening on the wrong port. First establish whether startup is progressing and identify any blocking initialization. Consider timeout configuration only if logs show that valid startup work needs more time, and check the current platform documentation for the available settings.
Dont SPAM