Maaz Zindani

Loading the index…

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

A Node.js gRPC client cannot connect: 14 UNAVAILABLE, failed to connect to all addresses

Error14 UNAVAILABLE: failed to connect to all addresses; last error: ...

Short answer

The client tried every address its target resolved to and none accepted a connection. The text after 'last error' tells you why, and a debug trace shows more. Check three things: the target has an explicit host and port, the server finished binding before the first call, and no HTTP proxy variable is catching traffic meant for localhost.

  • Applies to @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

    Turn on gRPC's own trace for connections and name resolution, then run the failing client once. The trace shows which address was tried and what happened.

    GRPC_VERBOSITY=DEBUG GRPC_TRACE=dns_resolver,connectivity_state,subchannel node client.js
  2. 2Match what you see, then jump to its fix

    1. 1The client target has no :port, or its port differs from the one the server bindsThe target has no port, or points at a different port than the server usesFix
    2. 2It fails only on startup or in a test that starts the server and the client in the same process, and works when you retry a moment laterThe first call runs before the server has finished bindingFix
    3. 3It fails on a machine or CI runner where http_proxy, https_proxy or grpc_proxy is set, even for localhostAn HTTP proxy variable is intercepting a local connectionFix

What does the error look like?

  • 14 UNAVAILABLE: failed to connect to all addresses; last error: ...
  • 14 UNAVAILABLE: No connection established. Last error: ...

Cause 1 of 3

The target has no port, or points at a different port than the server uses

1Check

gRPC resolves a plain host name with its DNS scheme, and the naming specification gives 443 as the default port when none is written. A server that listens on another port is never reached.

grep -rn "bindAsync\|credentials\.create" --include=*.js --include=*.ts --exclude-dir=node_modules .
ss -ltn | grep 50051

2Fix

Write host and port in the client target, matching the address the server binds. A literal IPv4 target skips name resolution.

// server
server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {});

// client
const client = new Service('localhost:50051', grpc.credentials.createInsecure());
// or, without DNS:
// new Service('ipv4:127.0.0.1:50051', grpc.credentials.createInsecure());

3Verify

A call returns a response, or at least a status other than 14 UNAVAILABLE.

node client.js

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The first call runs before the server has finished binding

1Check

bindAsync reports success through its callback. The grpc-js source marks start() as no longer needed since 1.10, so the server accepts connections once the bind has succeeded. A client call made before that finds nothing listening. On a version before 1.10, also call server.start() inside the callback, as the Node.js basics page does.

grep -rn "bindAsync" --include=*.js --include=*.ts --exclude-dir=node_modules .

2Fix

Wait for the bind callback before creating the client or running the first call.

function listen(server, address) {
  return new Promise((resolve, reject) => {
    server.bindAsync(address, grpc.ServerCredentials.createInsecure(), (err, port) => {
      if (err) reject(err);
      else resolve(port);
    });
  });
}

const port = await listen(server, '127.0.0.1:50051');
const client = new Service(`127.0.0.1:${port}`, grpc.credentials.createInsecure());

3Verify

Run the test or the startup path several times in a row; the error no longer appears.

for i in 1 2 3 4 5; do node client.js || break; done

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

An HTTP proxy variable is intercepting a local connection

1Check

grpc-js reads grpc_proxy, then https_proxy, then http_proxy, and connects through that proxy unless the host is listed in no_grpc_proxy or no_proxy.

env | grep -i proxy

2Fix

Exclude the local hosts from the proxy, or turn the proxy off for that channel with the grpc.enable_http_proxy option.

export no_grpc_proxy=localhost,127.0.0.1

// or in code
const client = new Service('localhost:50051', grpc.credentials.createInsecure(), {
  'grpc.enable_http_proxy': 0,
});

3Verify

Run the client again in the same shell; the call connects.

node client.js

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Wrap calls to services that may be starting or restarting in a retry with backoff. gRPC describes UNAVAILABLE as usually transient, and warns that retrying calls that are not idempotent is not always safe.
  • Keep the server address in one setting that both the server and the client read, so the port cannot drift.
  • In tests, wait for the bind callback and use the port it reports instead of a fixed number.
  • Keep the trace command from the first step in your project notes; the tracer names are listed in the grpc-node environment variables document.

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.