Troubleshooting

This guide will go over common Valkey GLIDE issues. If your issues persist, please feel free to reach out to Valkey GLIDE community for help.

Enable Client Logging

To help diagnose issues, you will need to enable client logging to DEBUG mode.

In many situations, clients surface errors as generic timeout errors as they try to reconnect. Enabling DEBUG logs may provide more context on the issue.

To enable logging, you will need to set the logger from within your application.

Python

from glide import Logger, Level

Logger.set_logger_config(Level.DEBUG)

Java

import glide.api.Logger;

Logger.setLoggerConfig(Logger.Level.DEBUG);

Node

import { Logger } from "@valkey/valkey-glide";

Logger.setLoggerConfig("debug");

Go

import (
    "github.com/valkey-io/valkey-glide/go/glide"
)

glide.SetLoggerConfig(glide.LogLevelDebug)

Tip

For more details on setting up logging, refer to the Logging Guide.

Timeout errors

This section troubleshoots timeout errors.

Single Node Failover

During a single node failover, the entire cluster becomes unavailable. Debug logs may show CLUSTER_DOWN errors.

This may happen if your cluster only has 2 shards, which is often the setup during testing.

In a cluster with only 2 shards, losing 1 shard means 50% of hash slots are unavailable. This forces the cluster into a CLUSTER_DOWN state to preserve data integrity. GLIDE reports this as timeouts because it keeps retrying against a cluster that refuses to serve requests.

Fix: Use a minimum of 3 shards (preferably 4+) for production. With 3 shards, losing one affects only ~33% of data, allowing the remaining nodes to stay online.

Failed to create GlideClusterClient

Received TimeoutError on startup and failed to create GlideClusterClient.

This happens when default connection timeouts (often ~250ms) are too aggressive for VPNs, cross-region links, or high-latency networks. To fix this, you must increase the connection timeout which is separate from the request timeout.

// Node.js Example
const client = await GlideClusterClient.createClient({
    addresses: [...],
    advancedConfiguration: {
        // Give the handshake at least 1-5 seconds
        connectionTimeout: 5000
    },
    // This is the request timeout, NOT connection timeout
    requestTimeout: 2000,
});