{"record":{"id":"8db167a347feeb88","repo":"router-for-me/CLIProxyAPI","slug":"home-cluster-discovery-transport-failed-w","errorCode":null,"errorMessage":"home cluster discovery transport failed: %w","messagePattern":"home cluster discovery transport failed: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/home/client.go","lineNumber":759,"sourceCode":"\t}\n\tif switched {\n\t\tif addr, ok := c.addr(); ok {\n\t\t\tlog.Infof(\"home cluster target switched to %s\", addr)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (c *Client) refreshClusterNodes(ctx context.Context) (bool, error) {\n\tif !c.clusterDiscoveryEnabled() {\n\t\treturn false, nil\n\t}\n\tif ctx == nil {\n\t\tctx = context.Background()\n\t}\n\tcmd, errClient := c.commandClient()\n\tif errClient != nil {\n\t\treturn false, fmt.Errorf(\"%w: %w\", errClusterDiscoveryTransport, errClient)\n\t}\n\tnodesCommand := cmd.Do(ctx, \"CLUSTER\", \"NODES\")\n\terrDo := nodesCommand.Err()\n\tif errDo != nil {\n\t\tvar redisErr redis.Error\n\t\tif !errors.As(errDo, &redisErr) {\n\t\t\treturn false, fmt.Errorf(\"%w: %w\", errClusterDiscoveryTransport, errDo)\n\t\t}\n\t\treturn false, errDo\n\t}\n\traw, errText := nodesCommand.Text()\n\tif errText != nil {\n\t\treturn false, errText\n\t}\n\n\tnodes, errParse := parseClusterNodesPayload([]byte(raw))\n\tif errParse != nil {\n\t\treturn false, errParse","sourceCodeStart":741,"sourceCodeEnd":777,"githubUrl":"https://github.com/router-for-me/CLIProxyAPI/blob/78f0c4079e3e6273d65d03b5549cffc898703264/internal/home/client.go#L741-L777","documentation":"Returned by refreshClusterNodes in internal/home/client.go: cluster discovery is enabled, but obtaining the command client failed before CLUSTER NODES could be sent. The error wraps errClusterDiscoveryTransport around the underlying client-construction failure (invalid address, disabled, fenced, or a TLS option error from redisOptionsLocked).","triggerScenarios":"Cluster discovery enabled while the base home client cannot be constructed — empty host/port (see 'home: invalid address'), client disabled or dispatch-fenced, or bad TLS material (mTLS pair mismatch, unreadable ca-cert).","commonSituations":"Enabling cluster discovery on a node whose home block was partially configured; TLS certs expired/rotated so client construction fails; startup race where discovery runs before full config load.","solutions":["Unwrap the error (errors.Unwrap / %v prints the chain) to find the real client-construction cause","Fix that underlying cause first: host/port set, TLS files valid and matching, client enabled","Only enable cluster discovery once the base connection verifies (ping/heartbeat healthy)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure base client health before enabling discovery\nif cfg.Home.ClusterDiscovery {\n    if strings.TrimSpace(cfg.Home.Host) == \"\" || cfg.Home.Port <= 0 {\n        return errors.New(\"cluster discovery requires valid home host/port\")\n    }\n    if err := preflightTLS(cfg.Home.TLS); err != nil { return err }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"cluster discovery transport failed\") {\n    if inner := errors.Unwrap(err); inner != nil {\n        log.Errorf(\"discovery unavailable, cause: %v — node map unchanged\", inner)\n    }\n}","preventionTips":["Gate cluster discovery on a successful first heartbeat","Log unwrapped causes; the sentinel alone hides the real problem"],"tags":["go","redis-cluster","discovery","tls","home"],"backgroundTag":null,"analyzedSha":"78f0c4079e3e6273d65d03b5549cffc898703264","analyzedAt":"2026-08-15T12:26:37.444Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}