{"record":{"id":"0f1c1fab7c367ec5","repo":"apache/cassandra","slug":"expecting-uri-in-variable-cassandra-config-fou","errorCode":null,"errorMessage":"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.","messagePattern":"Expecting URI in variable: \\[cassandra\\.config\\]\\. Found\\[(.+?)\\]\\. Please prefix the file with \\[(.+?)(.+?)\\] for local files and \\[(.+?)<server>(.+?)\\] for remote files\\. If you are executing this from an external tool, it needs to set Config\\.setClientMode\\(true\\) to avoid loading configuration\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/config/YamlConfigurationLoader.java","lineNumber":121,"sourceCode":"    private static URL getStorageConfigURL() throws ConfigurationException\n    {\n        String configUrl = CASSANDRA_CONFIG.getString();\n\n        URL url;\n        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    {","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/YamlConfigurationLoader.java#L103-L139","documentation":"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.","triggerScenarios":"Starting Cassandra with -Dcassandra.config=/etc/cassandra/cassandra.yaml (bare path without file: prefix) or another non-URI value that the classloader cannot resolve.","commonSituations":"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.","solutions":["Prefix the path with file:/// e.g. -Dcassandra.config=file:///etc/cassandra/cassandra.yaml","Ensure the file exists and is on the classpath if you intend it as a resource","If running in client/embedded-tool mode, set Config.setClientMode(true) so config loading is skipped"],"exampleFix":"// before\nSystem.setProperty(\"cassandra.config\", \"/etc/cassandra/cassandra.yaml\");\n// after\nSystem.setProperty(\"cassandra.config\", \"file:///etc/cassandra/cassandra.yaml\");","handlingStrategy":"validation","validationCode":"String cfg = System.getProperty(\"cassandra.config\", \"\");\nif (!cfg.isEmpty() && !cfg.startsWith(\"file:\") && !cfg.matches(\"[A-Za-z][A-Za-z0-9+.-]*:.*\"))\n    throw new IllegalArgumentException(\"cassandra.config must be a URI, e.g. file:///etc/cassandra/cassandra.yaml\");","typeGuard":"static boolean isUriConfigLocation(String s) {\n    return s != null && (s.startsWith(\"file:\") || java.net.URI.create(s).getScheme() != null);\n}","tryCatchPattern":"try { Config c = YamlConfigurationLoader.loadConfig(); }\ncatch (ConfigurationException e) { log.error(\"cassandra.config must be a URI: {}\", e.getMessage()); throw e; }","preventionTips":["Always use file:/// absolute URIs in -Dcassandra.config","Test launch scripts with the exact system properties before deployment","Set Config.setClientMode(true) in external/embedded tools that must not load server config"],"tags":["configuration","uri","startup"],"backgroundTag":"invalid-url-format","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"}