{"record":{"id":"b787a6ac6fcef14a","repo":"nathanmarz/storm","slug":"could-not-find-config-file-on-classpath-name","errorCode":null,"errorMessage":"Could not find config file on classpath ${name}","messagePattern":"Could not find config file on classpath (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"storm-core/src/jvm/backtype/storm/utils/Utils.java","lineNumber":129,"sourceCode":"    \n    public static List<URL> findResources(String name) {\n        try {\n            Enumeration<URL> resources = Thread.currentThread().getContextClassLoader().getResources(name);\n            List<URL> ret = new ArrayList<URL>();\n            while(resources.hasMoreElements()) {\n                ret.add(resources.nextElement());\n            }\n            return ret;\n        } catch(IOException e) {\n            throw new RuntimeException(e);\n        }\n    }\n\n    public static Map findAndReadConfigFile(String name, boolean mustExist) {\n        try {\n            HashSet<URL> resources = new HashSet<URL>(findResources(name));\n            if(resources.isEmpty()) {\n                if(mustExist) throw new RuntimeException(\"Could not find config file on classpath \" + name);\n                else return new HashMap();\n            }\n            if(resources.size() > 1) {\n                throw new RuntimeException(\"Found multiple \" + name + \" resources. You're probably bundling the Storm jars with your topology jar. \"\n                  + resources);\n            }\n            URL resource = resources.iterator().next();\n            Yaml yaml = new Yaml();\n            Map ret = (Map) yaml.load(new InputStreamReader(resource.openStream()));\n            if(ret==null) ret = new HashMap();\n            \n\n            return new HashMap(ret);\n            \n        } catch (IOException e) {\n            throw new RuntimeException(e);\n        }\n    }","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/nathanmarz/storm/blob/cdb116e942666973bc4eaa0df098d5bab82739e7/storm-core/src/jvm/backtype/storm/utils/Utils.java#L111-L147","documentation":"Utils.findAndReadConfigFile loads a YAML config resource from the classpath; when mustExist is true and findResources(name) returns nothing, it throws RuntimeException stating the config file could not be found on the classpath. Callers like readDefaultConfig and readStormConfig always require the file, so a missing default.yaml/storm.yaml resource is fatal.","triggerScenarios":"Calling Utils.findAndReadConfigFile(name, true) — directly or via readDefaultConfig()/readStormConfig() — when no classpath resource matches name (e.g. storm.yaml not present on the classpath, or default.yaml absent because the Storm jar is incomplete).","commonSituations":"Running a topology locally without storm.yaml on the classpath; packaging a topology jar that excludes Storm's config resources; wrong working directory/classloader so the resource isn't visible; typo in the config file name.","solutions":["Put storm.yaml on the classpath (usually in ~/.storm or passed via -Dstorm.conf.file / STORM_CONF_DIR) before running.","Verify the file name passed to findAndReadConfigFile matches an existing classpath resource exactly (case-sensitive, with extension).","Check the topology/uber jar isn't excluding *.yaml via build filters, or that you're not shading Storm out of the classpath.","If the file is genuinely optional, call findAndReadConfigFile(name, false) which returns an empty Map instead of throwing."],"exampleFix":"// before\nMap conf = Utils.findAndReadConfigFile(\"storm.yaml\", true);\n// after\nMap conf = Utils.findConfigFile(\"storm.yaml\") != null\n    ? Utils.findAndReadConfigFile(\"storm.yaml\", true)\n    : new HashMap();  // or fix classpath so storm.yaml is present","handlingStrategy":"try-catch","validationCode":"if (Utils.findResources(\"storm.yaml\").isEmpty()) {\n    throw new IllegalStateException(\"storm.yaml not on classpath; set STORM_CONF_DIR or -Dstorm.conf.file\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    conf = Utils.readStormConfig();\n} catch (RuntimeException e) {\n    if (e.getMessage().startsWith(\"Could not find config file\")) {\n        conf = new HashMap();  // fall back to defaults and warn\n    } else {\n        throw e;\n    }\n}","preventionTips":["Ensure storm.yaml lives in ~/.storm or a directory on the classpath on every machine that runs client or worker code.","Never assume the config exists — pass mustExist=false when it is optional.","Verify deployment scripts copy config files before launching workers.","Log the effective classpath when debugging config-loading failures."],"tags":["configuration","classpath","yaml","storm"],"backgroundTag":"config-file-not-found","analyzedSha":"cdb116e942666973bc4eaa0df098d5bab82739e7","analyzedAt":"2026-09-12T14:30:00.714Z","contentChangedAt":"2026-09-12T14:30:00.714Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}