{"record":{"id":"57ae5ee79c742f98","repo":"apache/cassandra","slug":"replacement-host-name-could-not-be-resolved-or-sco","errorCode":null,"errorMessage":"Replacement host name could not be resolved or scope_id was specified for a global IPv6 address","messagePattern":"Replacement host name could not be resolved or scope_id was specified for a global IPv6 address","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":2648,"sourceCode":"    }\n\n    public static InetAddressAndPort getReplaceAddress()\n    {\n        try\n        {\n            String replaceAddress = REPLACE_ADDRESS.getString();\n            if (replaceAddress != null)\n                return InetAddressAndPort.getByName(replaceAddress);\n\n            String replaceAddressFirsstBoot = REPLACE_ADDRESS_FIRST_BOOT.getString();\n            if (replaceAddressFirsstBoot != null)\n                return InetAddressAndPort.getByName(replaceAddressFirsstBoot);\n\n            return null;\n        }\n        catch (UnknownHostException e)\n        {\n            throw new RuntimeException(\"Replacement host name could not be resolved or scope_id was specified for a global IPv6 address\", e);\n        }\n    }\n\n    public static Collection<String> getReplaceTokens()\n    {\n        return tokensFromString(REPLACE_TOKEN.getString());\n    }\n\n    public static UUID getReplaceNode()\n    {\n        try\n        {\n            return UUID.fromString(REPLACE_NODE.getString());\n        }\n        catch (NullPointerException e)\n        {\n            return null;\n        }","sourceCodeStart":2630,"sourceCodeEnd":2666,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L2630-L2666","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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>)"],"exampleFix":"// before\ncassandra.replace_address_first_boot: dead-node-1.internal  # DNS gone\n// after\ncassandra.replace_address_first_boot: 10.0.0.42","handlingStrategy":"validation","validationCode":"String replace = System.getProperty(\"cassandra.replace_address_first_boot\");\nif (replace != null) {\n    java.net.InetAddress addr = java.net.InetAddress.getByName(replace); // throws if unresolvable\n    if (replace.contains(\"%\"))\n        throw new IllegalArgumentException(\"Remove IPv6 scope_id from replace address\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    InetAddressAndPort addr = getReplacementAddress();\n} catch (RuntimeException e) {\n    logger.error(\"Cannot resolve replacement address; check DNS or use an IP literal\", e);\n}","preventionTips":["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"],"tags":["network","dns","replacement","startup"],"backgroundTag":"invalid-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}