apache/cassandra · critical · ConfigurationException

Snitch metadata service URL '%s' is invalid. Please review s

Error message

Snitch metadata service URL '%s' is invalid. Please review snitch properties defined in the configured '%s' configuration file.

What it means

AbstractCloudMetadataServiceConnector validates the configured metadata service URL by converting it to a URI. Malformed URLs (MalformedURLException, URISyntaxException, or IllegalArgumentException) raise a ConfigurationException pointing at cassandra-rackdc.properties, since cloud snitches (EC2/GCE/Azure) fetch topology from that service.

Source

Thrown at src/java/org/apache/cassandra/locator/AbstractCloudMetadataServiceConnector.java:64

    protected final int requestTimeoutMs;

    private final SnitchProperties properties;

    public AbstractCloudMetadataServiceConnector(SnitchProperties snitchProperties)
    {
        this.properties = snitchProperties;
        String parsedMetadataServiceUrl = properties.get(METADATA_URL_PROPERTY, null);

        try
        {
            URL url = new URL(parsedMetadataServiceUrl);
            url.toURI();

            this.metadataServiceUrl = parsedMetadataServiceUrl;
        }
        catch (MalformedURLException | IllegalArgumentException | URISyntaxException ex)
        {
            throw new ConfigurationException(format("Snitch metadata service URL '%s' is invalid. Please review snitch properties " +
                                                    "defined in the configured '%s' configuration file.",
                                                    parsedMetadataServiceUrl,
                                                    CassandraRelevantProperties.CASSANDRA_RACKDC_PROPERTIES.getKey()),
                                             ex);
        }

        String metadataRequestTimeout = properties.get(METADATA_REQUEST_TIMEOUT_PROPERTY, DEFAULT_METADATA_REQUEST_TIMEOUT);

        try
        {
            this.requestTimeoutMs = new DurationSpec.IntMillisecondsBound(metadataRequestTimeout).toMilliseconds();
        }
        catch (IllegalArgumentException ex)
        {
            throw new ConfigurationException(format("%s as value of %s is invalid duration! " + ex.getMessage(),
                                                    metadataRequestTimeout,
                                                    METADATA_REQUEST_TIMEOUT_PROPERTY));
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Fix the metadata service URL property in cassandra-rackdc.properties to a fully qualified, valid absolute URI (e.g. http://169.254.169.254)
Remove stray spaces, quotes, or unexpanded environment placeholders from the property
Verify the property key name matches what your snitch version expects
Test the URL with a URI validator or `new URI(...)`/curl before restarting Cassandra

Example fix

// before (cassandra-rackdc.properties)
ec2_metadata_service_url=169.254.169.254/latest
// after
ec2_metadata_service_url=http://169.254.169.254/latest

Defensive patterns

Strategy: validation

Validate before calling

String url = props.getProperty("ec2_metadata_service_url");
try { new java.net.URI(url).toURL(); } catch (Exception e) { failStartup("invalid metadata service url: " + url); }

Type guard

boolean validUrl(String s) { try { new java.net.URI(s).toURL(); return true; } catch (Exception e) { return false; } }

Try / catch

try { startSnitch(); } catch (ConfigurationException e) { log.error("check {} : {}", cassandraRackdcFile, e.getMessage()); System.exit(1); }

Prevention

Always include the scheme (http://) in metadata service URLs
Avoid environment placeholder expansion in cassandra-rackdc.properties
Validate rackdc properties with config tooling before rollout
Test snitch config changes in staging with the same properties file

When it happens

Trigger: Startup of an EC2Snitch/Ec2MultiRegionSnitch/GceSnitch or similar where the metadata service URL property in cassandra-rackdc.properties is malformed (missing scheme, illegal characters, spaces, bad port).

Common situations: Typo'd or hand-edited cassandra-rackdc.properties; overriding metadata_service_url with an internal endpoint and missing 'http://'; shell interpolation leaving placeholders like ${HOST} unresolved.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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