{"record":{"id":"821f5cdeb599c26e","repo":"cilium/cilium","slug":"mismatched-maxconnectedclusters-local-d-remote","errorCode":null,"errorMessage":"mismatched MaxConnectedClusters; local=%d, remote=%d","messagePattern":"mismatched MaxConnectedClusters; local=(.+?), remote=(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/clustermesh/types/option.go","lineNumber":110,"sourceCode":"\n\treturn nil\n}\n\n// ExtendedClusterMeshEnabled returns true if MaxConnectedClusters value has\n// been set to a value larger than the default 255.\nfunc (c ClusterInfo) ExtendedClusterMeshEnabled() bool {\n\treturn c.MaxConnectedClusters != defaults.MaxConnectedClusters\n}\n\n// ValidateRemoteConfig validates the remote CiliumClusterConfig to ensure\n// compatibility with this cluster's configuration.\nfunc (c ClusterInfo) ValidateRemoteConfig(config CiliumClusterConfig) error {\n\tif err := ValidateClusterID(config.ID); err != nil {\n\t\treturn err\n\t}\n\n\tif c.ExtendedClusterMeshEnabled() && (c.MaxConnectedClusters != config.Capabilities.MaxConnectedClusters) {\n\t\treturn fmt.Errorf(\"mismatched MaxConnectedClusters; local=%d, remote=%d\", c.MaxConnectedClusters, config.Capabilities.MaxConnectedClusters)\n\t}\n\n\tswitch config.Capabilities.EndpointSlicesExportMode {\n\tcase EndpointSlicesExportModeServicesOnly, EndpointSlicesExportModeServicesAndEndpointSlices, EndpointSlicesExportModeEndpointSlicesOnly:\n\tdefault:\n\t\treturn fmt.Errorf(\"invalid EndpointSlicesExportMode %q\", config.Capabilities.EndpointSlicesExportMode)\n\t}\n\n\treturn nil\n}\n\n// QuirksConfig allows the user to configure how Cilium behaves when a set\n// of incompatible options are configured together into the agent.\ntype QuirksConfig struct {\n\t// AllowUnsafePolicySKBUsage determines whether to hard-fail startup\n\t// due to detection of a configuration combination that may trigger\n\t// connection impact in the dataplane due to clustermesh IDs\n\t// conflicting with other usage of skb->mark field. See GH-21330.","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/clustermesh/types/option.go#L92-L128","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\n# local: --max-connected-clusters=511\n# remote: default 255\n// after\n# both clusters: --max-connected-clusters=511\n# then reconnect the remote cluster","handlingStrategy":"validation","validationCode":"local, remote := info.MaxConnectedClusters, cfg.Capabilities.MaxConnectedClusters\nif info.ExtendedClusterMeshEnabled() && local != remote {\n    return fmt.Errorf(\"reconcile max-connected-clusters before connecting: local=%d remote=%d\", local, remote)\n}","typeGuard":null,"tryCatchPattern":"if err := info.ValidateRemoteConfig(cfg); err != nil {\n    if strings.Contains(err.Error(), \"mismatched MaxConnectedClusters\") {\n        // resync remote CiliumClusterConfig, then retry\n    }\n    return err\n}","preventionTips":["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"],"tags":["clustermesh","config-mismatch","max-connected-clusters"],"backgroundTag":"clustermesh-config-mismatch","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}