apache/cassandra · critical · ConfigurationException

Cannot locate . If this is a local file, please confirm…

Error message

Cannot locate <configUrl>.  If this is a local file, please confirm you've provided <required><pathSeparator> as a URI prefix.

What it means

The sibling error to the URI-format check: the cassandra.config value is a well-formed file: URI but the resource cannot be located by the classloader. YamlConfigurationLoader throws ConfigurationException advising to confirm the file: URI prefix and, implicitly, that the file exists and is readable/resolvable.

Solutions

1. Verify the file exists at the exact URI given (ls the path)
2. Use an absolute file: URI, e.g. file:///etc/cassandra/cassandra.yaml
3. Check spelling/permissions and that the file is readable by the Cassandra user
4. If the file should be a classpath resource, ensure it is on the classpath and reference it by resource name

Example fix

# before
-Dcassandra.config=file:///etc/cassandra/cassanda.yaml  # typo
# after
-Dcassandra.config=file:///etc/cassandra/cassandra.yaml

String cfg = System.getProperty("cassandra.config");
if (cfg != null && cfg.startsWith("file:")) {
    java.net.URI u = java.net.URI.create(cfg);
    if (!new java.io.File(u).canRead())
        throw new IllegalArgumentException("cassandra.yaml not readable at: " + cfg);
}

static boolean configLocationExists(String s) {
    try { return s != null && s.startsWith("file:") && new java.io.File(java.net.URI.create(s)).canRead(); }
    catch (Exception e) { return false; }
}

try { Config c = YamlConfigurationLoader.loadConfig(); }
catch (ConfigurationException e) { log.error("Cannot locate cassandra.config ({}): check path and file: prefix", e.getMessage()); throw e; }

When it happens

Trigger: -Dcassandra.config=file:///path/to/cassandra.yaml where the file does not exist, is misspelled, is not absolute, or is outside any classloader-visible location.

Common situations: Wrong path in custom deployments/containers; file deleted or mounted at a different path; relative file: URIs that the classloader cannot resolve; permission or typo issues in packaged distributions.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• Cannot replace a live node...
• Cannot replace same address when accord transactions are…
• Cannot reset state and replay from a save point; must…

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

Appendix: source

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

        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
    {
        if (storageConfigURL == null)
            storageConfigURL = getStorageConfigURL();

        return loadConfig(storageConfigURL);
    }

View on GitHub (pinned to 88fd0f6a0e)