Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

gRPC call to a Cloud Run service fails with 14 UNAVAILABLE

Error14 UNAVAILABLE

Short answer

Status 14 UNAVAILABLE means the call could not reach a working server right now. Against Cloud Run the usual reasons are a server that does not listen on the PORT variable, a client using an insecure channel instead of TLS on port 443, or a short outage that a retry with backoff would cover.

  • Applies to Cloud Run, @grpc/grpc-js 1.x, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at how the server binds and how the client creates its channel. The port and the credentials type decide which cause applies.

    grep -rn "bindAsync\|createInsecure\|createSsl\|PORT" --include=*.js --include=*.ts . --exclude-dir=node_modules
  2. 2Match what you see, then jump to its fix

    1. 1The container starts but requests never reach the serverThe server does not listen on the PORT Cloud Run gives itFix
    2. 2Works against localhost with insecure credentials, fails against the run.app URLThe client uses an insecure channel against the public URLFix
    3. 3The error is rare, comes in bursts, and goes away on the next callA transient failure with no retryFix

What does the error look like?

  • 14 UNAVAILABLE

Cause 1 of 3

The server does not listen on the PORT Cloud Run gives it

1Check

Cloud Run requires the server to listen on the port in the PORT environment variable. A hard-coded port such as 50051 is not the one Cloud Run sends traffic to.

grep -rn "bindAsync\|PORT" server.js

2Fix

Bind to PORT on all interfaces.

const port = process.env.PORT || 8080;
server.bindAsync(`0.0.0.0:${port}`, grpc.ServerCredentials.createInsecure(), () => {});

3Verify

Redeploy, then make one call from the client.

node client.js

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 2 of 3

The client uses an insecure channel against the public URL

1Check

Clients connect to the Cloud Run URL on port 443 using TLS. An insecure channel sends plain HTTP/2 to a TLS port.

grep -rn "createInsecure\|createSsl" client.js

2Fix

Use SSL credentials and the host on port 443.

const client = new MyService('my-service-abc123-ew.a.run.app:443',
                             grpc.credentials.createSsl());

3Verify

Make one call.

node client.js

Confirmed by grpc.io

Did this fix it?

Cause 3 of 3

A transient failure with no retry

1Check

The gRPC guide describes UNAVAILABLE as most likely a transient condition that retrying with a backoff can correct. It also names a server shutting down, or a connection breaking after data was sent, as cases that return it.

console.log(err.code, err.details);

2Fix

Retry the failing call with growing delays, but only for calls that are safe to repeat; retrying non-idempotent calls may apply their effect twice.

async function callWithRetry(fn, tries = 4) {
  for (let i = 0; i < tries; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.code !== grpc.status.UNAVAILABLE || i === tries - 1) throw e;
      await new Promise(r => setTimeout(r, 200 * 2 ** i));
    }
  }
}

3Verify

Wrap one call and send a burst of requests.

node client.js

Confirmed by grpc.io

Did this fix it?

How do I stop it coming back?

  • Read PORT from the environment in every Cloud Run server.
  • Test the client against the deployed URL with TLS, not only against localhost.
  • Retry only calls that are safe to repeat, with a backoff.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

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