apache/cassandra · error · ConfigurationException

CloudstackSnitch cannot handle invalid zone format

Error message

CloudstackSnitch cannot handle invalid zone format: %s

What it means

Thrown by CloudstackLocationProvider.resolveLocation() when the CloudStack metadata zone string does not split into exactly three '-'-separated parts. CloudstackSnitch expects zone format like 'pods-cloud1-host1' where the first two parts form the datacenter and the third the rack; anything else is rejected with a ConfigurationException.

Solutions

1. Rename the CloudStack zone to the expected 3-part hyphenated format (cloud-pod-host)
2. Verify the metadata endpoint returns only the raw zone name (curl the ZONE_NAME_QUERY_URI)
3. Use a different snitch/location provider if the environment is not CloudStack

Example fix

// before: zone "myZone" (1 part)
// after: rename CloudStack zone to expected format, e.g. "pods-cloud1-host1"
// -> datacenter "pods-cloud1", rack "host1"

String zone = connector.apiCall(ZONE_NAME_QUERY_URI);
if (zone == null || zone.split("-").length != 3) throw new IllegalArgumentException("Unexpected zone format: " + zone);

try { location = CloudstackLocationProvider.resolveLocation(connector); } catch (ConfigurationException e) { logger.error("Bad CloudStack zone format", e); throw e; }

When it happens

Trigger: Node startup with the Cloudstack location provider where the ZONE_NAME_QUERY_URI api call returns a zone string with a different number of hyphen-separated segments.

Common situations: Custom CloudStack zone names containing extra hyphens or none; querying the wrong metadata endpoint returning HTML/an error page; non-CloudStack environment misconfigured with the Cloudstack provider.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• CloudstackSnitch cannot access lease file.
• No metadata server could be found in lease file.
• No valid DHCP lease file could be found.
• Configuration must specify either node_proximity and…
• DC or rack not found in snitch properties, check your…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/locator/CloudstackLocationProvider.java:77

    public CloudstackLocationProvider(SnitchProperties snitchProperties) throws IOException
    {
        this(new DefaultCloudMetadataServiceConnector(snitchProperties.putIfAbsent(METADATA_URL_PROPERTY, csMetadataEndpoint())));
    }

    public CloudstackLocationProvider(AbstractCloudMetadataServiceConnector connector) throws IOException
    {
        super(connector, CloudstackLocationProvider::resolveLocation);
        logger.warn("{} is deprecated and not actively maintained. It will be removed in the next " +
                    "major version of Cassandra.", CloudstackSnitch.class.getName());
    }

    private static Location resolveLocation(AbstractCloudMetadataServiceConnector connector) throws IOException
    {
        String zone = connector.apiCall(ZONE_NAME_QUERY_URI);
        String[] zoneParts = zone.split("-");

        if (zoneParts.length != 3)
            throw new ConfigurationException("CloudstackSnitch cannot handle invalid zone format: " + zone);

        return new Location(zoneParts[0] + '-' + zoneParts[1], zoneParts[2]);
    }

    private static String csMetadataEndpoint() throws ConfigurationException
    {
        for (String lease_uri : LEASE_FILES)
        {
            try
            {
                File lease_file = new File(new URI(lease_uri));
                if (lease_file.exists())
                {
                    return csEndpointFromLease(lease_file);
                }
            }
            catch (Exception e)
            {

View on GitHub (pinned to 88fd0f6a0e)