{"record":{"id":"229cf2469d07672e","repo":"googleapis/mcp-toolbox","slug":"unable-to-connect-to-redis-cluster-s","errorCode":null,"errorMessage":"unable to connect to redis cluster: %s","messagePattern":"unable to connect to redis cluster: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/redis/redis.go","lineNumber":127,"sourceCode":"\tvar err error\n\tif r.ClusterEnabled {\n\t\t// Create a new Redis Cluster client\n\t\tclusterClient := redis.NewClusterClient(&redis.ClusterOptions{\n\t\t\tAddrs: r.Address,\n\t\t\t// PoolSize applies per cluster node and not for the whole cluster.\n\t\t\tPoolSize:                   10,\n\t\t\tConnMaxIdleTime:            60 * time.Second,\n\t\t\tMinIdleConns:               1,\n\t\t\tCredentialsProviderContext: authFn,\n\t\t\tUsername:                   r.Username,\n\t\t\tPassword:                   r.Password,\n\t\t\tTLSConfig:                  tlsConfig,\n\t\t})\n\t\terr = clusterClient.ForEachShard(ctx, func(ctx context.Context, shard *redis.Client) error {\n\t\t\treturn shard.Ping(ctx).Err()\n\t\t})\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"unable to connect to redis cluster: %s\", err)\n\t\t}\n\t\tclient = clusterClient\n\t\treturn client, nil\n\t}\n\n\t// Create a new Redis client\n\tstandaloneClient := redis.NewClient(&redis.Options{\n\t\tAddr:                       r.Address[0],\n\t\tPoolSize:                   10,\n\t\tConnMaxIdleTime:            60 * time.Second,\n\t\tMinIdleConns:               1,\n\t\tDB:                         r.Database,\n\t\tCredentialsProviderContext: authFn,\n\t\tUsername:                   r.Username,\n\t\tPassword:                   r.Password,\n\t\tTLSConfig:                  tlsConfig,\n\t})\n\t_, err = standaloneClient.Ping(ctx).Result()","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/redis/redis.go#L109-L145","documentation":"This error wraps the underlying failure returned by go-redis when a Redis Cluster client cannot ping any shard after connecting. The toolbox creates a redis.UniversalClient in cluster mode and calls ForEachShard with a Ping; if any shard fails to respond, initialization of the source aborts. The wrapped error reveals the true cause (auth, DNS, TLS, timeout).","triggerScenarios":"Redis source configured with clusterMode=true; Initialize calls initRedisClient; clusterClient.ForEachShard(ctx, ping) fails on one or more shards due to unreachable nodes, refused TCP connection, auth failure, or TLS handshake error.","commonSituations":"Wrong cluster node addresses or ports in the `addresses` field; cluster nodes behind NAT/firewall not reachable; Redis requirepass/ACL password mismatch; self-signed certs not matching server-ca/TLS config; cluster slots not yet assigned on a freshly created cluster.","solutions":["Verify each address in the Redis source config is a reachable cluster node: `redis-cli -h <host> -p <port> ping` from the toolbox host.","If the cluster requires auth, set `username`/`password` fields correctly (Redis 6+ ACL users need username).","If TLS is enabled on the cluster, configure `useServerCA` or `tlsCa` correctly; disable TLS only if the server is plaintext.","Check for firewall/NAT issues: cluster clients must reach every node's announced IP:port, not just the seed node.","Run `cluster info` / `cluster nodes` on the cluster to confirm it is up and slots are covered."],"exampleFix":"// before\nsources:\n  my-redis:\n    kind: redis\n    addresses: [\"localhost:7000\"]\n    clusterMode: true\n// after\nsources:\n  my-redis:\n    kind: redis\n    addresses: [\"redis-node-1:6379\", \"redis-node-2:6379\", \"redis-node-3:6379\"]\n    clusterMode: true\n    password: ${REDIS_PASSWORD}","handlingStrategy":"validation","validationCode":"// Before configuring the toolbox source, verify every cluster node answers PING\nfor addr in \"${REDIS_NODES[@]}\"; do\n  host=${addr%%:*}; port=${addr##*:}\n  redis-cli -h \"$host\" -p \"$port\" --no-auth-warning ping || echo \"unreachable: $addr\"\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["List ALL cluster node addresses in the config, not just a seed — clients must reach every node's announced address.","Store credentials in env vars/secret references and verify with `redis-cli -a <pw> ping`.","Align TLS settings (server CA, client certs) with the actual server TLS mode before deploying.","Run `cluster nodes` to confirm the cluster is healthy and slots are fully covered."],"tags":["redis","connection","cluster","go"],"backgroundTag":"connection-refused","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}