Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

node-redis throws ConnectionTimeoutError on connect

ErrorConnectionTimeoutError: Connection timeout

Short answer

node-redis raises ConnectionTimeoutError when the socket does not connect within socket.connectTimeout, which is 5000 ms by default. The usual reasons are a wrong host or port, a platform with no network path to Redis (App Engine needs a VPC connector for Memorystore), or a timeout set too low for a slow link.

  • Applies to Node.js 22, node-redis 5, Memorystore for Redis, App Engine standard
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the host and port the client really uses, and test that port from the same runtime. Do this before changing any option.

    console.log('redis target', process.env.REDISHOST, process.env.REDISPORT);
    // from a shell on the same host:
    // nc -zv "$REDISHOST" "$REDISPORT"
  2. 2Match what you see, then jump to its fix

    1. 1The same code connects from your laptop or a Compute Engine VM, but times out on App Engine standard.App Engine has no path to Memorystore (no VPC connector)Fix
    2. 2The client has no URL or host set, so it uses its defaults.The client is pointed at the wrong host or portFix
    3. 3The failure happens after about five seconds, and nc to the port succeeds but is slow.The connect timeout is too low for the networkFix

What does the error look like?

  • ConnectionTimeoutError: Connection timeout
  • Redis Client Error ConnectionTimeoutError

Cause 1 of 3

App Engine has no path to Memorystore (no VPC connector)

1Check

App Engine standard reaches it only through a Serverless VPC Access connector that is in the same region as the app and attached to the Redis instance's authorized network.

gcloud redis instances describe my-redis --region us-central1

2Fix

Create the connector in the app's region on that network, then reference it in app.yaml together with the Redis address.

# app.yaml
vpc_access_connector:
  name: 'projects/my-project/locations/us-central1/connectors/my-connector'
env_variables:
  REDISHOST: '10.0.0.3'
  REDISPORT: '6379'

3Verify

Deploy and call a route that runs PING.

# redeploy, then call a route that runs client.ping()

Confirmed by docs.cloud.google.com

Did this fix it?

Cause 2 of 3

The client is pointed at the wrong host or port

1Check

Without options node-redis connects to localhost on port 6379. An empty or misspelled environment variable silently gives you that default.

grep -rn "createClient" src/

2Fix

Pass the address explicitly, with a URL or with socket host and port, and add an error listener so failures are logged.

import { createClient } from 'redis';

const client = createClient({
  socket: {
    host: process.env.REDISHOST,
    port: Number(process.env.REDISPORT),
  },
});
client.on('error', err => console.error('Redis Client Error', err));
await client.connect();

3Verify

Start the app and confirm a command works.

await client.set('probe', '1');
console.log(await client.get('probe'));

Confirmed by redis.io

Did this fix it?

Cause 3 of 3

The connect timeout is too low for the network

1Check

socket.connectTimeout defaults to 5000 ms. A cross-region or cold-start path can need longer.

grep -rn "connectTimeout" src/

2Fix

Raise connectTimeout. Do this only after the port test works; a longer timeout does not fix an unreachable host.

const client = createClient({
  url: process.env.REDIS_URL,
  socket: { connectTimeout: 15000 },
});

3Verify

Restart the app and watch for the error to stop.

node app.js

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Always attach client.on('error', ...) so connection errors are logged.
  • Read host and port from the environment and fail fast when they are missing.
  • Keep Redis in the same region as the app.

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

Next step

Want this handled for good?

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