mismatched MaxConnectedClusters; local=%d, remote=%d

Error message

mismatched MaxConnectedClusters; local=%d, remote=%d

What it means

ClusterInfo.ValidateRemoteConfig compares the local cluster's max-connected-clusters with the MaxConnectedClusters capability advertised by a remote cluster's CiliumClusterConfig. When extended clustermesh is enabled locally (MaxConnectedClusters != default 255), both sides must agree, otherwise cluster ID encoding differs and traffic would be misrouted; the function fails with the local and remote values.

Source

Thrown at pkg/clustermesh/types/option.go:110

	return nil
}

// ExtendedClusterMeshEnabled returns true if MaxConnectedClusters value has
// been set to a value larger than the default 255.
func (c ClusterInfo) ExtendedClusterMeshEnabled() bool {
	return c.MaxConnectedClusters != defaults.MaxConnectedClusters
}

// ValidateRemoteConfig validates the remote CiliumClusterConfig to ensure
// compatibility with this cluster's configuration.
func (c ClusterInfo) ValidateRemoteConfig(config CiliumClusterConfig) error {
	if err := ValidateClusterID(config.ID); err != nil {
		return err
	}

	if c.ExtendedClusterMeshEnabled() && (c.MaxConnectedClusters != config.Capabilities.MaxConnectedClusters) {
		return fmt.Errorf("mismatched MaxConnectedClusters; local=%d, remote=%d", c.MaxConnectedClusters, config.Capabilities.MaxConnectedClusters)
	}

	switch config.Capabilities.EndpointSlicesExportMode {
	case EndpointSlicesExportModeServicesOnly, EndpointSlicesExportModeServicesAndEndpointSlices, EndpointSlicesExportModeEndpointSlicesOnly:
	default:
		return fmt.Errorf("invalid EndpointSlicesExportMode %q", config.Capabilities.EndpointSlicesExportMode)
	}

	return nil
}

// QuirksConfig allows the user to configure how Cilium behaves when a set
// of incompatible options are configured together into the agent.
type QuirksConfig struct {
	// AllowUnsafePolicySKBUsage determines whether to hard-fail startup
	// due to detection of a configuration combination that may trigger
	// connection impact in the dataplane due to clustermesh IDs
	// conflicting with other usage of skb->mark field. See GH-21330.

View on GitHub (pinned to ac7b90affa)

Solutions

Set the same --max-connected-clusters value on both clusters and restart Cilium
Update the remote cluster's CiliumClusterConfig (cmctl clustermesh or cilium-clustermesh-apiserver deployment) to match the local value
If extended clustermesh is not needed, revert local --max-connected-clusters to the default 255

Example fix

// before
# local: --max-connected-clusters=511
# remote: default 255
// after
# both clusters: --max-connected-clusters=511
# then reconnect the remote cluster

Defensive patterns

Strategy: validation

Validate before calling

local, remote := info.MaxConnectedClusters, cfg.Capabilities.MaxConnectedClusters
if info.ExtendedClusterMeshEnabled() && local != remote {
    return fmt.Errorf("reconcile max-connected-clusters before connecting: local=%d remote=%d", local, remote)
}

Try / catch

if err := info.ValidateRemoteConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "mismatched MaxConnectedClusters") {
        // resync remote CiliumClusterConfig, then retry
    }
    return err
}

Prevention

Keep --max-connected-clusters identical across all clusters in the mesh
Reconnect remote clusters after changing extended-clustermesh settings
Version-control the clustermesh values so all clusters are deployed from the same template

When it happens

Trigger: Local ClusterInfo has MaxConnectedClusters != 255 (extended clustermesh) and ValidateRemoteConfig() is called with a remote CiliumClusterConfig whose Capabilities.MaxConnectedClusters differs (e.g. local 511, remote 255).

Common situations: Connecting clusters where only one was configured with --max-connected-clusters=511, or after changing the value on one side without reconfiguring and restarting the remote cluster so its cached CiliumClusterConfig in the clustermesh-apiserver is stale.

Related errors

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/821f5cdeb599c26e. Report an issue: GitHub.