apache/cassandra · error · ConfigurationException

Unable to retrieve initial zone or platform fault domain fro

Error message

Unable to retrieve initial zone or platform fault domain from cloud metadata service. This is required for registration, please check configuration

What it means

Thrown by AzureCloudLocationProvider.resolveLocation() when neither the zone nor the platformFaultDomain field could be read from the Azure instance metadata response. The rack cannot be determined without one of these, and a rack is required for registration.

Source

Thrown at src/java/org/apache/cassandra/locator/AzureCloudLocationProvider.java:85

        JsonNode location = jsonNode.get("location");
        JsonNode zone = jsonNode.get("zone");
        JsonNode platformFaultDomain = jsonNode.get("platformFaultDomain");

        String datacenter;
        String rack;

        if (location == null || location.isNull() || location.asText().isEmpty())
            throw new ConfigurationException("Unable to retrieve initial location from cloud metadata service. " +
                                             "This is required for registration, please check configuration");
        else
            datacenter = location.asText();

        if (zone == null || zone.isNull() || zone.asText().isEmpty())
        {
            if (platformFaultDomain == null || platformFaultDomain.isNull() || platformFaultDomain.asText().isEmpty())
            {
                throw new ConfigurationException("Unable to retrieve initial zone or platform fault domain from cloud metadata service. " +
                                                 "This is required for registration, please check configuration");
            }
            else
            {
                rack = platformFaultDomain.asText();
            }
        }
        else
        {
            rack = zone.asText();
        }

        return new Location(datacenter + connector.getProperties().getDcSuffix(), "rack-" + rack);
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use an IMDS api-version that returns platformFaultDomain or zone (e.g. 2021-02-01 or newer)
2. Verify compute metadata exposes platformFaultDomain via curl on the node
3. Deploy VMs into an availability zone so zone metadata is populated

Example fix

// before
GET /metadata/instance/compute?api-version=2017-04-02

// after
GET /metadata/instance/compute?api-version=2021-02-01

// verify zone/fault domain exposure before enabling provider
curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute?api-version=2021-02-01" | grep -Ei 'zone|platformFaultDomain'

try { provider.resolveLocation(connector); } catch (ConfigurationException e) { logger.error("Neither zone nor platformFaultDomain present in IMDS response", e); throw e; }

When it happens

Trigger: Node startup with the Azure location provider where the metadata JSON lacks both 'zone' and 'platformFaultDomain' (null/empty), e.g. regions without availability zones and an IMDS version that omits platformFaultDomain.

Common situations: Azure regions without availability zones combined with an outdated api-version; locked-down IMDS where faultDomain is not exposed; mistyped property name in the provider config.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• Unable to retrieve initial location from cloud metadata serv
• HttpException(conn.getResponseCode(), conn.getResponseMessag
• Unable to resolve initial location using cloud metadata serv
• Configuration must specify either node_proximity and initial
• Snitch metadata service URL '%s' is invalid. Please review s

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