microsoft/garnet · critical · GarnetException

Invalid endpoint format {Address} {Port}.

Error message

Invalid endpoint format {Address} {Port}.

What it means

GarnetException thrown during Options.Initialize when Format.TryParseAddressList fails to parse the Address/Port pair into at least one valid endpoint, or returns zero endpoints. This is the bind-address validation gate: the server cannot start without at least one valid listen endpoint. The error message echoes the raw Address and Port values for diagnostics.

Source

Thrown at libs/host/Configuration/Options.cs:766

                DeviceType = DeviceType.Native;
            }

            var deviceType = GetDeviceType(logger);

            var useAzureStorage = deviceType == DeviceType.AzureStorage;
            if (useAzureStorage && string.IsNullOrEmpty(AzureStorageConnectionString) && string.IsNullOrEmpty(AzureStorageServiceUri))
                throw new InvalidAzureConfiguration("Cannot use AzureStorage device without supplying storage-string or storage-service-uri");
            if (useAzureStorage && !string.IsNullOrEmpty(AzureStorageConnectionString) && !string.IsNullOrEmpty(AzureStorageServiceUri))
                throw new InvalidAzureConfiguration("Cannot use AzureStorage device with both storage-string and storage-service-uri");

            var logDir = LogDir;
            if (!useAzureStorage && enableStorageTier) logDir = new DirectoryInfo(string.IsNullOrEmpty(logDir) ? "." : logDir).FullName;
            var checkpointDir = CheckpointDir;
            if (!useAzureStorage) checkpointDir = new DirectoryInfo(string.IsNullOrEmpty(checkpointDir) ? (string.IsNullOrEmpty(logDir) ? "." : logDir) : checkpointDir).FullName;

            if (!Format.TryParseAddressList(Address, Port, out var endpoints, out _, ProtectedMode == CommandLineBooleanOption.True)
              || endpoints.Length == 0)
                throw new GarnetException($"Invalid endpoint format {Address} {Port}.");

            EndPoint[] clusterAnnounceEndpoint = null;
            if (ClusterAnnounceIp != null)
            {
                ClusterAnnouncePort = ClusterAnnouncePort == 0 ? Port : ClusterAnnouncePort;
                clusterAnnounceEndpoint = Format.TryCreateEndpoint(ClusterAnnounceIp, ClusterAnnouncePort, tryConnect: false, logger: logger);
                if (clusterAnnounceEndpoint == null || !endpoints.Any(endpoint =>
                    endpoint is IPEndPoint listenEp && clusterAnnounceEndpoint[0] is IPEndPoint announceEp &&
                    listenEp.Port == announceEp.Port &&
                    (listenEp.Address.Equals(announceEp.Address) ||
                     listenEp.Address.Equals(IPAddress.Any) ||
                     listenEp.Address.Equals(IPAddress.IPv6Any))))
                    throw new GarnetException("Cluster announce endpoint does not match list of listen endpoints provided!");
            }

            if (!string.IsNullOrEmpty(UnixSocketPath))
                endpoints = [.. endpoints, new UnixDomainSocketEndPoint(UnixSocketPath)];

View on GitHub (pinned to 951b0fc683)

Solutions

1. Check that --address is a valid IP literal (or '*'/empty for all interfaces) and --port is a numeric value in 1–65535.
2. For IPv6, ensure the address is bracketed, e.g., [::1]:6379.
3. If using ProtectedMode, verify the address is permitted under protected-mode rules.
4. Confirm the Address and Port fields are not swapped or empty in the config file.

Example fix

// before
options.Address = "127.0.0.O";
options.Port = 6379;

// after
options.Address = "127.0.0.1";
options.Port = 6379;

using System.Net;

bool IsValidBindAddress(string address, int port)
{
    if (port < 1 || port > 65535) return false;
    if (string.IsNullOrEmpty(address) || address == "*") return true;
    return IPAddress.TryParse(address, out _);
}

void ValidateEndpoint(Options opts)
{
    if (!IsValidBindAddress(opts.Address, opts.Port))
        throw new InvalidOperationException($"Invalid endpoint: address='{opts.Address}' port={opts.Port}");
}

try
{
    options.Initialize(logger);
}
catch (GarnetException ex) when (ex.Message.StartsWith("Invalid endpoint format"))
{
    logger.LogCritical("Endpoint address/port is invalid: {Address}:{Port}", options.Address, options.Port);
    throw;
}

When it happens

Trigger: Setting --address or --port to a malformed or empty value; providing a port of 0 with no address; a hostname that cannot be parsed as an IP; a port string that is non-numeric; an IPv6 address missing brackets; ProtectedMode rejecting the address.

Common situations: Typo in the bind address (e.g., '127.0.0.O' instead of '127.0.0.1'); port set to a non-numeric or out-of-range value; copying a config across environments with a placeholder address; IPv6 address not wrapped in brackets in a combined address:port string.

Related errors

• Cluster announce endpoint does not match list of listen endp
• Cannot use AzureStorage device without supplying storage-str
• Cannot use AzureStorage device with both storage-string and
• Gossip sample fraction should be in range [0,100]
• Incompatible revivification record size and count cardinalit

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/9e5bae67d62330ff. Report an issue: GitHub.