{"record":{"id":"e63a3ab8aaaa2530","repo":"apache/cassandra","slug":"cannot-locate-configurl-if-this-is-a-local-fil","errorCode":null,"errorMessage":"Cannot locate <configUrl>.  If this is a local file, please confirm you've provided <required><pathSeparator> as a URI prefix.","messagePattern":"Cannot locate <configUrl>\\.  If this is a local file, please confirm you've provided <required><pathSeparator> as a URI prefix\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/config/YamlConfigurationLoader.java","lineNumber":126,"sourceCode":"        try\n        {\n            url = new URL(configUrl);\n            url.openStream().close(); // catches well-formed but bogus URLs\n        }\n        catch (Exception e)\n        {\n            ClassLoader loader = DatabaseDescriptor.class.getClassLoader();\n            url = loader.getResource(configUrl);\n            if (url == null)\n            {\n                String required = \"file:\" + File.pathSeparator() + File.pathSeparator();\n                if (!configUrl.startsWith(required))\n                    throw new ConfigurationException(String.format(\n                        \"Expecting URI in variable: [cassandra.config]. Found[%s]. Please prefix the file with [%s%s] for local \" +\n                        \"files and [%s<server>%s] for remote files. If you are executing this from an external tool, it needs \" +\n                        \"to set Config.setClientMode(true) to avoid loading configuration.\",\n                        configUrl, required, File.pathSeparator(), required, File.pathSeparator()));\n                throw new ConfigurationException(\"Cannot locate \" + configUrl + \".  If this is a local file, please confirm you've provided \" + required + File.pathSeparator() + \" as a URI prefix.\");\n            }\n        }\n\n        logger.info(\"Configuration location: {}\", url);\n\n        return url;\n    }\n\n    private static URL storageConfigURL;\n\n    @Override\n    public Config loadConfig() throws ConfigurationException\n    {\n        if (storageConfigURL == null)\n            storageConfigURL = getStorageConfigURL();\n\n        return loadConfig(storageConfigURL);\n    }","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/YamlConfigurationLoader.java#L108-L144","documentation":"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.","triggerScenarios":"-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.","commonSituations":"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.","solutions":["Verify the file exists at the exact URI given (ls the path)","Use an absolute file: URI, e.g. file:///etc/cassandra/cassandra.yaml","Check spelling/permissions and that the file is readable by the Cassandra user","If the file should be a classpath resource, ensure it is on the classpath and reference it by resource name"],"exampleFix":"# before\n-Dcassandra.config=file:///etc/cassandra/cassanda.yaml  # typo\n# after\n-Dcassandra.config=file:///etc/cassandra/cassandra.yaml","handlingStrategy":"validation","validationCode":"String cfg = System.getProperty(\"cassandra.config\");\nif (cfg != null && cfg.startsWith(\"file:\")) {\n    java.net.URI u = java.net.URI.create(cfg);\n    if (!new java.io.File(u).canRead())\n        throw new IllegalArgumentException(\"cassandra.yaml not readable at: \" + cfg);\n}","typeGuard":"static boolean configLocationExists(String s) {\n    try { return s != null && s.startsWith(\"file:\") && new java.io.File(java.net.URI.create(s)).canRead(); }\n    catch (Exception e) { return false; }\n}","tryCatchPattern":"try { Config c = YamlConfigurationLoader.loadConfig(); }\ncatch (ConfigurationException e) { log.error(\"Cannot locate cassandra.config ({}): check path and file: prefix\", e.getMessage()); throw e; }","preventionTips":["Verify the exact path exists and is readable by the Cassandra user before startup","Use absolute file: URIs; avoid typos by generating the property from a checked-in script","In containers, confirm the config volume is mounted at the expected path"],"tags":["configuration","file-not-found","startup"],"backgroundTag":"config-file-not-found","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}