{"record":{"id":"8e716155a486939e","repo":"Grasscutters/Grasscutter","slug":"unable-to-load-the-primary-fallback-and-en-us","errorCode":null,"errorMessage":"Unable to load the primary, fallback, and 'en-US' language files.","messagePattern":"Unable to load the primary, fallback, and 'en-US' language files\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/main/java/emu/grasscutter/utils/lang/Language.java","lineNumber":218,"sourceCode":"                return new LanguageStreamDescription(actualLanguageCode, null);\n            }\n\n            file = Grasscutter.class.getResourceAsStream(\"/languages/\" + fallback);\n        }\n\n        if (file == null) { // Fallback the fallback language.\n            Grasscutter.getLogger()\n                    .warn(\"Failed to load language file: \" + fallback + \", falling back to: en-US.json\");\n            actualLanguageCode = \"en-US\";\n            if (cachedLanguages.containsKey(actualLanguageCode)) {\n                return new LanguageStreamDescription(actualLanguageCode, null);\n            }\n\n            file = Grasscutter.class.getResourceAsStream(\"/languages/en-US.json\");\n        }\n\n        if (file == null)\n            throw new RuntimeException(\n                    \"Unable to load the primary, fallback, and 'en-US' language files.\");\n\n        return new LanguageStreamDescription(actualLanguageCode, file);\n    }\n\n    private static Int2ObjectMap<String> loadTextMapFile(String language, IntSet nameHashes) {\n        Int2ObjectMap<String> output = new Int2ObjectOpenHashMap<>();\n        try (BufferedReader file =\n                Files.newBufferedReader(\n                        getResourcePath(\"TextMap/TextMap\" + language + \".json\"), StandardCharsets.UTF_8)) {\n            Matcher matcher = textMapKeyValueRegex.matcher(\"\");\n            return new Int2ObjectOpenHashMap<>(\n                    file.lines()\n                            .sequential()\n                            .map(matcher::reset) // Side effects, but it's faster than making a new one\n                            .filter(Matcher::find)\n                            .filter(\n                                    m ->","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/Grasscutters/Grasscutter/blob/f373827a83d3e688fd3c6afb1e1c3759ca1d61c9/src/main/java/emu/grasscutter/utils/lang/Language.java#L200-L236","documentation":"Language.getLanguageTextMapKey / load logic tries the requested language file, then a fallback, then the bundled /languages/en-US.json; if the en-US resource stream is also null, it throws this RuntimeException. This means the language resource files are not on the classpath at all — a broken installation, not a bad user config.","triggerScenarios":"Calling Language.load/getTextMap (or starting Grasscutter) when none of the requested language, fallback, and embedded en-US.json resources resolve, i.e. Grasscutter.class.getResourceAsStream(\"/languages/en-US.json\") returns null.","commonSituations":"Running from a partially built jar where resources weren't packaged; deleting or renaming src/main/resources/languages; launching classes without the resources directory on the classpath; corrupted gradle build output.","solutions":["Rebuild the project so resources are packaged: run the gradle build (e.g. ./gradlew build) and launch the produced jar","Verify src/main/resources/languages/en-US.json exists in the repo and inside the jar (jar tf grasscutter.jar | grep languages)","If running from an IDE/exploded classpath, ensure src/main/resources is marked as a resources root","Check any -DlanguageCode or config language value is not the root cause, though fixing the classpath is the real fix"],"exampleFix":"// before (launching bare classes without resources on classpath)\njava -cp classes emu.grasscutter.Grasscutter\n// after\n./gradlew build && java -jar grasscutter.jar","handlingStrategy":"fallback","validationCode":"boolean languageResourcesPresent() {\n  return Grasscutter.class.getResource(\"/languages/en-US.json\") != null;\n}","typeGuard":"null","tryCatchPattern":"try {\n  Language lang = Language.load(\"en-US\");\n} catch (RuntimeException e) {\n  logger.fatal(\"Language resources missing from classpath; rebuild the jar.\");\n  System.exit(1);\n}","preventionTips":["Always build and run via the gradle jar, not bare class directories","Verify en-US.json exists under src/main/resources/languages in the packaged artifact","Add a startup check that getResource(\"/languages/en-US.json\") != null","Don't delete or rename resource files when editing language configs"],"tags":["resources","classpath","i18n","initialization"],"backgroundTag":"missing-resource-file","analyzedSha":"f373827a83d3e688fd3c6afb1e1c3759ca1d61c9","analyzedAt":"2026-09-03T22:43:49.407Z","contentChangedAt":"2026-09-03T22:43:49.407Z","schemaVersion":2},"datasetVersion":"2026-09-11T07:07:21.782Z"}