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)

PHP

use Glide\Logger;

Logger::setLoggerConfig(Logger::LEVEL_DEBUG);

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.

Connection Timeout on Client Creation

Received timeout error on startup and failed to create client.

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

Python

from glide import (
    GlideClusterClientConfiguration,
    AdvancedGlideClusterClientConfiguration,
    NodeAddress
)

config = GlideClusterClientConfiguration(
    addresses=[NodeAddress("localhost", 6379)],
    request_timeout=5000,  # Request timeout in milliseconds
    advanced_configuration=AdvancedGlideClusterClientConfiguration(
        connection_timeout=10000  # Connection timeout in milliseconds
    )
)
client = await GlideClusterClient.create(config)

Java

import glide.api.models.configuration.*;

GlideClusterClientConfiguration config =
    GlideClusterClientConfiguration.builder()
        .address(NodeAddress.builder().host("localhost").port(6379).build())
        .requestTimeout(5000)  // Request timeout in milliseconds
        .advancedConfiguration(
            AdvancedGlideClusterClientConfiguration.builder()
                .connectionTimeout(10000)  // Connection timeout in milliseconds
                .build()
        )
        .build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();

Node

const client = await GlideClusterClient.createClient({
    addresses: [{ host: "localhost", port: 6379 }],
    requestTimeout: 5000,  // Request timeout in milliseconds
    advancedConfiguration: {
        connectionTimeout: 10000  // Connection timeout in milliseconds
    }
});

Go

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

cfg := config.NewGlideClusterClientConfiguration().
    WithAddress(&config.NodeAddress{Host: "localhost", Port: 6379}).
    WithRequestTimeout(5 * time.Second)

advCfg := config.NewAdvancedGlideClusterClientConfiguration().
    WithConnectionTimeout(10 * time.Second)

cfg.WithAdvancedConfiguration(advCfg)
client, err := glide.NewGlideClusterClient(cfg)

PHP

$client = new ValkeyGlide();
$client->connect(
    addresses: [['host' => 'localhost', 'port' => 6379]],
    request_timeout: 5000,  // Request timeout in milliseconds
    advanced_config: [
        'connection_timeout' => 10000,  // Connection timeout in milliseconds
        'socket_timeout' => 5000  // Socket read/write timeout in milliseconds
    ]
);

Extension Not Loaded (PHP)

If you receive an error that the valkey_glide extension is not loaded, verify the extension is properly installed and enabled.

Check if extension is loaded:

if (!extension_loaded('valkey_glide')) {
    echo "Valkey GLIDE extension is not loaded!\n";
    exit(1);
}

Verify installation:

php -m | grep valkey_glide
php -r "if (extension_loaded('valkey_glide')) echo 'SUCCESS'; else echo 'ERROR';"

Fix: Ensure the extension is added to your php.ini:

extension=valkey_glide

Find your php.ini location with php --ini and restart your PHP service after making changes.