apache/cassandra · critical · ConfigurationException

Expecting URI in variable: [cassandra.config]. Found

Error message

Expecting URI in variable: [cassandra.config]. Found[%s]. Please prefix the file with [%s%s] for local files and [%s<server>%s] for remote files. If you are executing this from an external tool, it needs to set Config.setClientMode(true) to avoid loading configuration.

What it means

YamlConfigurationLoader.getStorageConfigURL() resolves the cassandra.config system property as a classpath resource or URI. If the value is not found as a resource and does not even start with the expected 'file:' URI prefix, it throws ConfigurationException telling the caller a URI (not a bare path) is expected.

Solutions

1. Prefix the path with file:/// e.g. -Dcassandra.config=file:///etc/cassandra/cassandra.yaml
2. Ensure the file exists and is on the classpath if you intend it as a resource
3. If running in client/embedded-tool mode, set Config.setClientMode(true) so config loading is skipped

Example fix

// before
System.setProperty("cassandra.config", "/etc/cassandra/cassandra.yaml");
// after
System.setProperty("cassandra.config", "file:///etc/cassandra/cassandra.yaml");

String cfg = System.getProperty("cassandra.config", "");
if (!cfg.isEmpty() && !cfg.startsWith("file:") && !cfg.matches("[A-Za-z][A-Za-z0-9+.-]*:.*"))
    throw new IllegalArgumentException("cassandra.config must be a URI, e.g. file:///etc/cassandra/cassandra.yaml");

static boolean isUriConfigLocation(String s) {
    return s != null && (s.startsWith("file:") || java.net.URI.create(s).getScheme() != null);
}

try { Config c = YamlConfigurationLoader.loadConfig(); }
catch (ConfigurationException e) { log.error("cassandra.config must be a URI: {}", e.getMessage()); throw e; }

When it happens

Trigger: Starting Cassandra with -Dcassandra.config=/etc/cassandra/cassandra.yaml (bare path without file: prefix) or another non-URI value that the classloader cannot resolve.

Common situations: Custom launch scripts passing plain filesystem paths; container entrypoints overriding cassandra.config without the file:/ absolute URI; external tools loading config without setting client mode.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• Cannot locate . If this is a local file, please confirm…
• Cannot replace a live node...
• Cannot replace same address when accord transactions are…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/YamlConfigurationLoader.java:121

    private static URL getStorageConfigURL() throws ConfigurationException
    {
        String configUrl = CASSANDRA_CONFIG.getString();

        URL url;
        try
        {
            url = new URL(configUrl);
            url.openStream().close(); // catches well-formed but bogus URLs
        }
        catch (Exception e)
        {
            ClassLoader loader = DatabaseDescriptor.class.getClassLoader();
            url = loader.getResource(configUrl);
            if (url == null)
            {
                String required = "file:" + File.pathSeparator() + File.pathSeparator();
                if (!configUrl.startsWith(required))
                    throw new ConfigurationException(String.format(
                        "Expecting URI in variable: [cassandra.config]. Found[%s]. Please prefix the file with [%s%s] for local " +
                        "files and [%s<server>%s] for remote files. If you are executing this from an external tool, it needs " +
                        "to set Config.setClientMode(true) to avoid loading configuration.",
                        configUrl, required, File.pathSeparator(), required, File.pathSeparator()));
                throw new ConfigurationException("Cannot locate " + configUrl + ".  If this is a local file, please confirm you've provided " + required + File.pathSeparator() + " as a URI prefix.");
            }
        }

        logger.info("Configuration location: {}", url);

        return url;
    }

    private static URL storageConfigURL;

    @Override
    public Config loadConfig() throws ConfigurationException
    {

View on GitHub (pinned to 88fd0f6a0e)