apache/cassandra · error · ConfigurationException

Unable to resolve initial location using cloud metadata serv

Error message

Unable to resolve initial location using cloud metadata service connector

What it means

Thrown by CloudMetadataLocationProvider.initialLocation() when the cloud metadata connector's I/O fails (IOException) while resolving the node's location, wrapped as a ConfigurationException. The node cannot determine its datacenter/rack from the cloud metadata service, which is required for snitch-based placement.

Source

Thrown at src/java/org/apache/cassandra/locator/CloudMetadataLocationProvider.java:58

    {
        this.connector = connector;
        this.locationResolver = locationResolver;
    }

    @Override
    public final Location initialLocation()
    {
        if (location == null)
        {
            try
            {
                location = locationResolver.resolve(connector);
                logger.info(format("%s using datacenter: %s, rack: %s, connector: %s, properties: %s",
                                   getClass().getName(), location.datacenter, location.rack, connector, connector.getProperties()));
            }
            catch (IOException e)
            {
                throw new ConfigurationException("Unable to resolve initial location using cloud metadata service connector", e);
            }
        }
        return location;
    }

    public interface LocationResolver
    {
        Location resolve(AbstractCloudMetadataServiceConnector connector) throws IOException;
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the metadata service endpoint is reachable from the node (curl the connector URL)
2. Check firewall rules allow access to the link-local metadata address
3. Correct the cassandra.yaml connector endpoint/timeout properties
4. Fall back to configuring datacenter/rack manually (e.g. use a non-cloud snitch with cassandra-rackdc.properties)

Example fix

// before
cassandra.cloud_metadata_service_endpoint: http://169.254.169.254/wrong/path

// after
cassandra.cloud_metadata_service_endpoint: http://169.254.169.254/latest/meta-data/placement/availability-zone

// reachability check before startup
new URL(endpoint).openConnection().setConnectTimeout(2000); // succeeds => metadata service reachable

try { return provider.initialLocation(connector); } catch (ConfigurationException e) { logger.error("Cloud metadata unreachable ({})", e.getCause()); throw e; }

When it happens

Trigger: initialLocation() during node startup when connector.apiCall/resolve throws IOException — metadata service unreachable, timeout, HTTP error, or DNS failure.

Common situations: Node not running in the expected cloud (no metadata endpoint at 169.254.169.254); firewall/iptables blocking link-local traffic; network flakiness at boot; wrong endpoint override in cassandra.yaml.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• HttpException(conn.getResponseCode(), conn.getResponseMessag
• Configured ${configName} "${intf}" could not be found
• Configured ${configName} "${intf}" was found, but had no add
• Set listen_address OR listen_interface, not both
• Configuration must specify either node_proximity and initial

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