{"record":{"id":"606a7cd46283e7a7","repo":"microsoft/garnet","slug":"cluster-announce-endpoint-does-not-match-list-of-l","errorCode":null,"errorMessage":"Cluster announce endpoint does not match list of listen endpoints provided!","messagePattern":"Cluster announce endpoint does not match list of listen endpoints provided!","errorType":"validation","errorClass":"GarnetException","httpStatus":null,"severity":"critical","filePath":"libs/host/Configuration/Options.cs","lineNumber":779,"sourceCode":"            var checkpointDir = CheckpointDir;\n            if (!useAzureStorage) checkpointDir = new DirectoryInfo(string.IsNullOrEmpty(checkpointDir) ? (string.IsNullOrEmpty(logDir) ? \".\" : logDir) : checkpointDir).FullName;\n\n            if (!Format.TryParseAddressList(Address, Port, out var endpoints, out _, ProtectedMode == CommandLineBooleanOption.True)\n              || endpoints.Length == 0)\n                throw new GarnetException($\"Invalid endpoint format {Address} {Port}.\");\n\n            EndPoint[] clusterAnnounceEndpoint = null;\n            if (ClusterAnnounceIp != null)\n            {\n                ClusterAnnouncePort = ClusterAnnouncePort == 0 ? Port : ClusterAnnouncePort;\n                clusterAnnounceEndpoint = Format.TryCreateEndpoint(ClusterAnnounceIp, ClusterAnnouncePort, tryConnect: false, logger: logger);\n                if (clusterAnnounceEndpoint == null || !endpoints.Any(endpoint =>\n                    endpoint is IPEndPoint listenEp && clusterAnnounceEndpoint[0] is IPEndPoint announceEp &&\n                    listenEp.Port == announceEp.Port &&\n                    (listenEp.Address.Equals(announceEp.Address) ||\n                     listenEp.Address.Equals(IPAddress.Any) ||\n                     listenEp.Address.Equals(IPAddress.IPv6Any))))\n                    throw new GarnetException(\"Cluster announce endpoint does not match list of listen endpoints provided!\");\n            }\n\n            if (!string.IsNullOrEmpty(UnixSocketPath))\n                endpoints = [.. endpoints, new UnixDomainSocketEndPoint(UnixSocketPath)];\n\n            // Unix file permission octal to UnixFileMode\n            var unixSocketPermissions = (UnixFileMode)Convert.ToInt32(UnixSocketPermission.ToString(), 8);\n\n            var revivBinRecordSizes = this.RevivBinRecordSizes?.ToArray();\n            var revivBinRecordCounts = this.RevivBinRecordCounts?.ToArray();\n            bool hasRecordSizes = revivBinRecordSizes?.Length > 0, hasRecordCounts = revivBinRecordCounts?.Length > 0;\n            bool useRevivBinsPowerOf2 = enableRevivification; // may be overridden\n\n            if (hasRecordSizes)\n            {\n                if (hasRecordCounts && revivBinRecordCounts.Length > 1 && revivBinRecordCounts.Length != revivBinRecordSizes.Length)\n                    throw new Exception(\"Incompatible revivification record size and count cardinality.\");\n                if (RevivInChainOnly.GetValueOrDefault())","sourceCodeStart":761,"sourceCodeEnd":797,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/host/Configuration/Options.cs#L761-L797","documentation":"GarnetException thrown during Options.Initialize when ClusterAnnounceIp is set but the resulting announce endpoint (ClusterAnnounceIp:ClusterAnnouncePort) does not match any of the parsed listen endpoints by address and port. The match allows wildcard addresses (IPAddress.Any / IPv6Any) but requires the port to align. This prevents a node from announcing a cluster address that clients cannot actually reach on the listen socket.","triggerScenarios":"Setting --cluster-announce-ip to a value whose port (defaulting to the listen Port) differs from all listen endpoint ports; announcing an IP that is not among the bind addresses and is not a wildcard; a multi-endpoint bind where the announce port matches none.","commonSituations":"NAT/container environments where the announce IP is set correctly but the announce port was overridden to a wrong value; multi-port deployments where the listen endpoints use different ports than the announce; copying cluster config between nodes without updating the announce IP.","solutions":["Ensure ClusterAnnouncePort matches the port of one of your listen endpoints (or leave it 0 to default to Port).","Set ClusterAnnounceIp to an address that is either one of your bind addresses or matches a wildcard bind (0.0.0.0/::).","If behind NAT, set the announce IP to the externally reachable IP and ensure the announce port matches the externally mapped port that forwards to a real listen port.","Remove --cluster-announce-ip if clustering is not needed."],"exampleFix":"// before: announce port does not match listen port\noptions.Address = \"0.0.0.0\";\noptions.Port = 6379;\noptions.ClusterAnnounceIp = \"10.0.0.5\";\noptions.ClusterAnnouncePort = 7000;\n\n// after: announce port aligns with listen port\noptions.Address = \"0.0.0.0\";\noptions.Port = 6379;\noptions.ClusterAnnounceIp = \"10.0.0.5\";\noptions.ClusterAnnouncePort = 6379;","handlingStrategy":"validation","validationCode":"using System.Net;\nusing System.Linq;\n\nbool AnnounceMatchesListen(string announceIp, int announcePort, EndPoint[] listenEndpoints)\n{\n    if (string.IsNullOrEmpty(announceIp)) return true;\n    var announceAddr = IPAddress.Parse(announceIp);\n    return listenEndpoints.OfType<IPEndPoint>().Any(le =>\n        le.Port == announcePort &&\n        (le.Address.Equals(announceAddr) ||\n         le.Address.Equals(IPAddress.Any) ||\n         le.Address.Equals(IPAddress.IPv6Any)));\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    options.Initialize(logger);\n}\ncatch (GarnetException ex) when (ex.Message.Contains(\"Cluster announce endpoint\"))\n{\n    logger.LogCritical(\"Cluster announce {Ip}:{Port} does not match any listen endpoint.\", options.ClusterAnnounceIp, options.ClusterAnnouncePort);\n    throw;\n}","preventionTips":["Ensure ClusterAnnouncePort matches a real listen port (or leave it 0 to inherit Port).","In NAT environments, verify the announce IP is externally reachable and maps to a listen port.","Document the announce/listen relationship in the node's deployment config."],"tags":["config","cluster","endpoint","startup","announce","validation","options"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}