router-for-me/CLIProxyAPI · error

home cluster discovery transport failed: %w

Error message

home cluster discovery transport failed: %w

What it means

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).

Source

Thrown at internal/home/client.go:759

	}
	if switched {
		if addr, ok := c.addr(); ok {
			log.Infof("home cluster target switched to %s", addr)
		}
	}
	return nil
}

func (c *Client) refreshClusterNodes(ctx context.Context) (bool, error) {
	if !c.clusterDiscoveryEnabled() {
		return false, nil
	}
	if ctx == nil {
		ctx = context.Background()
	}
	cmd, errClient := c.commandClient()
	if errClient != nil {
		return false, fmt.Errorf("%w: %w", errClusterDiscoveryTransport, errClient)
	}
	nodesCommand := cmd.Do(ctx, "CLUSTER", "NODES")
	errDo := nodesCommand.Err()
	if errDo != nil {
		var redisErr redis.Error
		if !errors.As(errDo, &redisErr) {
			return false, fmt.Errorf("%w: %w", errClusterDiscoveryTransport, errDo)
		}
		return false, errDo
	}
	raw, errText := nodesCommand.Text()
	if errText != nil {
		return false, errText
	}

	nodes, errParse := parseClusterNodesPayload([]byte(raw))
	if errParse != nil {
		return false, errParse

View on GitHub (pinned to 78f0c4079e)

Solutions

1. Unwrap the error (errors.Unwrap / %v prints the chain) to find the real client-construction cause
2. Fix that underlying cause first: host/port set, TLS files valid and matching, client enabled
3. Only enable cluster discovery once the base connection verifies (ping/heartbeat healthy)

// ensure base client health before enabling discovery
if cfg.Home.ClusterDiscovery {
    if strings.TrimSpace(cfg.Home.Host) == "" || cfg.Home.Port <= 0 {
        return errors.New("cluster discovery requires valid home host/port")
    }
    if err := preflightTLS(cfg.Home.TLS); err != nil { return err }
}

if err != nil && strings.Contains(err.Error(), "cluster discovery transport failed") {
    if inner := errors.Unwrap(err); inner != nil {
        log.Errorf("discovery unavailable, cause: %v — node map unchanged", inner)
    }
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• home ca fingerprint is required
• home ca fingerprint mismatch
• home ca certificate pem is invalid
• client key pem is invalid
• client key is not rsa

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/8db167a347feeb88. Report an issue: GitHub.