{"record":{"id":"682ccdd138a1322b","repo":"antlr/antlr4","slug":"filestream-is-only-available-when-running-in-node","errorCode":null,"errorMessage":"FileStream is only available when running in Node!","messagePattern":"FileStream is only available when running in Node!","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"runtime/JavaScript/src/antlr4/FileStream.js","lineNumber":22,"sourceCode":" */\n\nimport InputStream from './InputStream.js';\nimport CharStream from './CharStream.js';\nconst isNode =\n\ttypeof process !== \"undefined\" &&\n\tprocess.versions != null &&\n\tprocess.versions.node != null;\nimport fs from 'fs';\n\n/**\n * This is an InputStream that is loaded from a file all at once\n * when you construct the object.\n */\nexport default class FileStream extends InputStream {\n\n\tstatic fromPath(path, encoding, callback) {\n\t\tif(!isNode)\n\t\t\tthrow new Error(\"FileStream is only available when running in Node!\");\n\t\tfs.readFile(path, encoding, function(err, data) {\n\t\t\tlet is = null;\n\t\t\tif (data !== null) {\n\t\t\t\tis = new CharStream(data, true);\n\t\t\t}\n\t\t\tcallback(err, is);\n\t\t});\n\n\t}\n\n\tconstructor(fileName, encoding, decodeToUnicodeCodePoints) {\n\t\tif(!isNode)\n\t\t\tthrow new Error(\"FileStream is only available when running in Node!\");\n\t\tconst data = fs.readFileSync(fileName, encoding || \"utf-8\" );\n\t\tsuper(data, decodeToUnicodeCodePoints);\n\t\tthis.fileName = fileName;\n\t}\n}","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/antlr/antlr4/blob/7d5770395bb7b02eb56e7c62662cb1d7c08f42a3/runtime/JavaScript/src/antlr4/FileStream.js#L4-L40","documentation":"During ErrorManager format initialization, ANTLR loads the StringTemplate message-format group file (e.g. org/antlr/v4/tool/templates/messages/formats/antlr.stg) and collects any load-time errors in a static initSTListener. If that listener has any errors after the group file loads, the ANTLR tool assumes its own installation is corrupted: it prints the listener's error output via rawError (straight to System.err, because the error machinery itself is not trusted) and then panics. This is a fatal environment/installation error, not a grammar error.","triggerScenarios":"Calling new Tool(options) or otherwise triggering ErrorManager.setFormat(formatName) when the .stg resource on the classpath is present but malformed: truncated download, edited/corrupted jar, a conflicting resource shadowing the real one earlier on the classpath, or a jar built with a broken/modified messages template. Specifically it fires when loadedFormat.load() ran and initSTListener.errors is non-empty (ErrorManager.java:250-254).","commonSituations":"A Maven/Gradle dependency resolved to a corrupted or truncated antlr4 jar (flaky proxy/cache); someone replaced or shaded the org/antlr/v4/tool/templates/messages/formats/antlr.stg resource with an incompatible version during an uber-jar/relocation build; mixing antlr4 jar versions where the tool jar and runtime/templates come from different releases; manually editing template files inside the jar to customize message formats.","solutions":["Force a clean re-download of the antlr4 tool jar (e.g. mvn -U or delete ~/.m2/repository/org/antlr/... / Gradle cache) so the .stg resource is intact.","Check for duplicate/shadowing resources: run with -verbose:class or inspect the classpath for another org/antlr/v4/tool/templates/messages/formats/<format>.stg ahead of the official jar, and remove the conflicting artifact.","Ensure the antlr4 tool jar version matches across all modules (no mixed 4.x versions in one classpath or shaded jar).","If you customized the .stg file, restore the original from the official distribution and reapply changes carefully, verifying it is valid StringTemplate v4 group syntax.","Verify jar integrity: unzip -p antlr4-<version>.jar org/antlr/v4/tool/templates/messages/formats/antlr.stg | head and compare against a freshly downloaded distribution."],"exampleFix":"# before: mixed/corrupted artifacts on classpath\njava -cp 'antlr-4.7-shaded.jar:antlr-4.13.1-complete.jar' org.antlr.v4.Tool MyGrammar.g4\n# -> ErrorManager panics: can't load messages format file\n\n# after: single intact official tool jar\njava -cp 'antlr-4.13.1-complete.jar' org.antlr.v4.Tool MyGrammar.g4","handlingStrategy":"validation","validationCode":"// Before invoking the ANTLR tool, verify the message-format resource loads and is sane\nClassLoader cl = Thread.currentThread().getContextClassLoader();\njava.net.URL url = cl.getResource(\"org/antlr/v4/tool/templates/messages/formats/antlr.stg\");\nif (url == null) {\n    url = org.antlr.v4.tool.ErrorManager.class.getClassLoader()\n            .getResource(\"org/antlr/v4/tool/templates/messages/formats/antlr.stg\");\n}\nif (url == null) throw new IllegalStateException(\"antlr4 tool jar missing from classpath\");\ntry (java.io.InputStream in = url.openStream()) {\n    String stg = new String(in.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);\n    if (!stg.contains(\"location\") || !stg.contains(\"message\") || !stg.contains(\"report\")) {\n        throw new IllegalStateException(\"antlr.stg on classpath is truncated: \" + url);\n    }\n}","typeGuard":null,"tryCatchPattern":"// Only at the outermost tool-invocation boundary; cause is already printed to System.err\ntry {\n    Tool tool = new Tool(args);\n    tool.processGrammarsOnCommandLine();\n} catch (Error e) { // ErrorManager.panic() throws java.lang.Error, not Exception\n    if (e.getMessage() != null && e.getMessage().contains(\"ErrorManager panic\")) {\n        // installation/classpath problem: fail the build with a clear message\n        throw new IllegalStateException(\"ANTLR tool installation corrupted; see stderr above\", e);\n    }\n    throw e;\n}","preventionTips":["Pin one exact antlr4 version in every module and build plugin; never mix tool jars from different 4.x releases.","Exclude org/antlr/v4/tool/templates/** from jar shading, relocation, and minimization steps.","Verify jar checksums (or re-download on cache miss) in CI rather than trusting partially-downloaded artifacts.","Never edit template files inside the shipped jar; if you need custom formats, add a new .stg under a different format name."],"tags":["antlr","installation","classpath","stringtemplate","corrupted-jar","fatal"],"backgroundTag":null,"analyzedSha":"7d5770395bb7b02eb56e7c62662cb1d7c08f42a3","analyzedAt":"2026-08-14T14:47:56.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}