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.

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.

Appendix: 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)