apache/cassandra · error · ConfigurationException

Unknown host in epState for

Error message

Unknown host in epState for

What it means

GossipHelper.getAddressesFromEndpointState builds a NodeAddresses record by resolving INTERNAL_ADDRESS_AND_PORT/RPC_ADDRESS etc. from gossip endpoint state; any UnknownHostException during resolution is rethrown as ConfigurationException since the advertised addresses can't be resolved and the node cannot be migrated.

Source

Thrown at src/java/org/apache/cassandra/tcm/compatibility/GossipHelper.java:259

            return NodeState.LEFT;
        if (status.isEmpty())
            return NodeState.REGISTERED;
        throw new IllegalStateException("Can't upgrade the first node when STATUS = " + status + " for node " + endpoint);
    }

    public static NodeAddresses getAddressesFromEndpointState(InetAddressAndPort endpoint, EndpointState epState)
    {
        if (endpoint.equals(getBroadcastAddressAndPort()))
            return NodeAddresses.current();
        try
        {
            InetAddressAndPort local = getEitherState(endpoint, epState, INTERNAL_ADDRESS_AND_PORT, INTERNAL_IP, DatabaseDescriptor.getStoragePort());
            InetAddressAndPort nativeAddress = getEitherState(endpoint, epState, NATIVE_ADDRESS_AND_PORT, RPC_ADDRESS, DatabaseDescriptor.getNativeTransportPort());
            return new NodeAddresses(UUID.randomUUID(), endpoint, local, nativeAddress);
        }
        catch (UnknownHostException e)
        {
            throw new ConfigurationException("Unknown host in epState for " + endpoint + " : " + epState, e);
        }
    }

    private static InetAddressAndPort getEitherState(InetAddressAndPort endpoint,
                                                     EndpointState epState,
                                                     ApplicationState primaryState,
                                                     ApplicationState deprecatedState,
                                                     int defaultPortForDeprecatedState) throws UnknownHostException
    {
        if (epState.getApplicationState(primaryState) != null)
        {
            return getByName(epState.getApplicationState(primaryState).value);
        }
        else if (epState.getApplicationState(deprecatedState) != null)
        {
            return getByNameOverrideDefaults(epState.getApplicationState(deprecatedState).value, defaultPortForDeprecatedState);
        }
        else

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Fix the offending node's config to advertise literal IPs (broadcast_address, native_transport_address) rather than unresolvable hostnames
  2. Clean stale gossip entries for decommissioned nodes before migration (removenode/assassinate)
  3. Check DNS/resolv.conf health on the upgrading node if hostname-based addresses are used
  4. Re-run the upgrade after the endpoint state is corrected

Example fix

// before (offending node cassandra.yaml)
native_transport_address: old-host.internal.example   # DNS gone
// after
native_transport_address: 10.0.0.12
Defensive patterns

Strategy: try-catch

Validate before calling

for (InetAddressAndPort addr : advertisedAddresses(epState)) {
    try { InetAddress.getByName(addr.getAddress().getHostName()); }
    catch (UnknownHostException e) { log.error("Unresolvable address {} on {}", addr, endpoint); }
}

Try / catch

try { NodeAddresses a = GossipHelper.getAddressesFromEndpointState(endpoint, epState); }
catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Unknown host in epState")) { /* fix DNS / use literal IPs, clean stale gossip */ }
    else throw e;
}

Prevention

When it happens

Trigger: During gossip-to-TCM upgrade, an endpoint's gossip state advertises an unresolvable host (hostname instead of IP, or an IP string that fails to parse/resolve) in INTERNAL_ADDRESS_AND_PORT, INTERNAL_IP, RPC_ADDRESS, or NATIVE_ADDRESS_AND_PORT.

Common situations: Nodes configured with hostnames in broadcast/native_address settings whose DNS no longer resolves; stale gossip from removed machines; typo'd address application states; IPv4/IPv6 mismatches.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/82a75e6c3adce513. Report an issue: GitHub.