apache/cassandra · error · ConfigurationException

Unable to retrieve initial location from cloud metadata serv

Error message

Unable to retrieve initial location from cloud metadata service. This is required for registration, please check configuration

What it means

Thrown by AzureCloudLocationProvider.resolveLocation() when the Azure instance metadata service returned a response from which the location (region) field could not be extracted — null JSON node, JSON null, or empty text. A location (datacenter) is mandatory for snitch registration, so startup fails with a ConfigurationException.

Source

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

        super(connector, AzureCloudLocationProvider::resolveLocation);
    }

    static Location resolveLocation(AbstractCloudMetadataServiceConnector connector) throws IOException
    {
        String apiVersion = connector.getProperties().get(API_VERSION_PROPERTY_KEY, DEFAULT_API_VERSION);
        String response = connector.apiCall(format(METADATA_QUERY_TEMPLATE, apiVersion),
                                            ImmutableMap.of(METADATA_HEADER, "true"));
        JsonNode jsonNode = JsonUtils.JSON_OBJECT_MAPPER.readTree(response);

        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
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the node actually runs in Azure and the IMDS endpoint (169.254.169.254) is reachable
2. Check cassandra.yaml azure metadata connector settings (endpoint URL, timeouts)
3. Ensure the location/region property name configured for the provider matches the Azure compute metadata response
4. Remove the Azure cloud provider config if the node is not in Azure

Example fix

# before
cassandra.cloud_metadata_service_endpoint: http://wrong-host/metadata/instance

# after
cassandra.cloud_metadata_service_endpoint: http://169.254.169.254/metadata/instance?api-version=2021-02-01

// pre-check on the node before startup
curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute?api-version=2021-02-01" | grep -i location

try { location = provider.resolveLocation(connector); } catch (ConfigurationException e) { logger.error("Azure metadata location missing; check IMDS", e); throw e; }

When it happens

Trigger: Node startup with azure.CloudStack/Azure location provider where the metadata call succeeds but the region field is missing/empty — e.g. endpoint misconfigured, non-Azure VM, or IMDS response shape changed.

Common situations: Running a Cassandra node on a non-Azure machine configured with the Azure location provider; Azure IMDS unreachable/proxied so the resolver parses an empty or partial response; wrong metadata service URL override in cassandra.yaml.

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 zone or platform fault domain fro
• Configuration must specify either node_proximity and initial
• Snitch metadata service URL '%s' is invalid. Please review s
• %s as value of %s is invalid duration! %s
• HttpException(conn.getResponseCode(), conn.getResponseMessag

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