apache/cassandra · error · RuntimeException

Replacement host name could not be resolved or scope_id was

Error message

Replacement host name could not be resolved or scope_id was specified for a global IPv6 address

What it means

When replacing a dead node, the configured replacement address (cassandra.replace_address_first_boot) is resolved via InetAddressAndPort.getByName; an UnknownHostException is rethrown as RuntimeException noting that the host name could not be resolved, or a scope_id was given for a global IPv6 address.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:2648

    }

    public static InetAddressAndPort getReplaceAddress()
    {
        try
        {
            String replaceAddress = REPLACE_ADDRESS.getString();
            if (replaceAddress != null)
                return InetAddressAndPort.getByName(replaceAddress);

            String replaceAddressFirsstBoot = REPLACE_ADDRESS_FIRST_BOOT.getString();
            if (replaceAddressFirsstBoot != null)
                return InetAddressAndPort.getByName(replaceAddressFirsstBoot);

            return null;
        }
        catch (UnknownHostException e)
        {
            throw new RuntimeException("Replacement host name could not be resolved or scope_id was specified for a global IPv6 address", e);
        }
    }

    public static Collection<String> getReplaceTokens()
    {
        return tokensFromString(REPLACE_TOKEN.getString());
    }

    public static UUID getReplaceNode()
    {
        try
        {
            return UUID.fromString(REPLACE_NODE.getString());
        }
        catch (NullPointerException e)
        {
            return null;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Fix the hostname spelling or use a resolvable IP literal in cassandra.replace_address_first_boot
Remove the replace_address property after the replacement completes (it is first-boot-only)
Use an IPv4 address or global IPv6 without scope_id
Verify DNS resolution from the node (e.g. getent hosts <name>)

Example fix

// before
cassandra.replace_address_first_boot: dead-node-1.internal  # DNS gone
// after
cassandra.replace_address_first_boot: 10.0.0.42

Defensive patterns

Strategy: validation

Validate before calling

String replace = System.getProperty("cassandra.replace_address_first_boot");
if (replace != null) {
    java.net.InetAddress addr = java.net.InetAddress.getByName(replace); // throws if unresolvable
    if (replace.contains("%"))
        throw new IllegalArgumentException("Remove IPv6 scope_id from replace address");
}

Try / catch

try {
    InetAddressAndPort addr = getReplacementAddress();
} catch (RuntimeException e) {
    logger.error("Cannot resolve replacement address; check DNS or use an IP literal", e);
}

Prevention

Use IP literals for replace_address to avoid DNS dependency
Remove replace_address_first_boot after first successful boot
Never include IPv6 scope_ids in configured addresses

When it happens

Trigger: cassandra.replace_address_first_boot (or replace_address) set to a hostname DNS cannot resolve; IPv6 literal with %scope_id on a global address; startup with replace options set.

Common situations: Operator leaves replace_address in config from a prior replacement or misspells the host; DNS entry removed after node was replaced; IPv6 literal copied with scope id.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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