antlr/antlr4 · critical · Error

FileStream is only available when running in Node!

Error message

FileStream is only available when running in Node!

What it means

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.

Source

Thrown at runtime/JavaScript/src/antlr4/FileStream.js:22

 */

import InputStream from './InputStream.js';
import CharStream from './CharStream.js';
const isNode =
	typeof process !== "undefined" &&
	process.versions != null &&
	process.versions.node != null;
import fs from 'fs';

/**
 * This is an InputStream that is loaded from a file all at once
 * when you construct the object.
 */
export default class FileStream extends InputStream {

	static fromPath(path, encoding, callback) {
		if(!isNode)
			throw new Error("FileStream is only available when running in Node!");
		fs.readFile(path, encoding, function(err, data) {
			let is = null;
			if (data !== null) {
				is = new CharStream(data, true);
			}
			callback(err, is);
		});

	}

	constructor(fileName, encoding, decodeToUnicodeCodePoints) {
		if(!isNode)
			throw new Error("FileStream is only available when running in Node!");
		const data = fs.readFileSync(fileName, encoding || "utf-8" );
		super(data, decodeToUnicodeCodePoints);
		this.fileName = fileName;
	}
}

View on GitHub (pinned to 7d5770395b)

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.

Example fix

# before: mixed/corrupted artifacts on classpath
java -cp 'antlr-4.7-shaded.jar:antlr-4.13.1-complete.jar' org.antlr.v4.Tool MyGrammar.g4
# -> ErrorManager panics: can't load messages format file

# after: single intact official tool jar
java -cp 'antlr-4.13.1-complete.jar' org.antlr.v4.Tool MyGrammar.g4

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking the ANTLR tool, verify the message-format resource loads and is sane
ClassLoader cl = Thread.currentThread().getContextClassLoader();
java.net.URL url = cl.getResource("org/antlr/v4/tool/templates/messages/formats/antlr.stg");
if (url == null) {
    url = org.antlr.v4.tool.ErrorManager.class.getClassLoader()
            .getResource("org/antlr/v4/tool/templates/messages/formats/antlr.stg");
}
if (url == null) throw new IllegalStateException("antlr4 tool jar missing from classpath");
try (java.io.InputStream in = url.openStream()) {
    String stg = new String(in.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
    if (!stg.contains("location") || !stg.contains("message") || !stg.contains("report")) {
        throw new IllegalStateException("antlr.stg on classpath is truncated: " + url);
    }
}

Try / catch

// Only at the outermost tool-invocation boundary; cause is already printed to System.err
try {
    Tool tool = new Tool(args);
    tool.processGrammarsOnCommandLine();
} catch (Error e) { // ErrorManager.panic() throws java.lang.Error, not Exception
    if (e.getMessage() != null && e.getMessage().contains("ErrorManager panic")) {
        // installation/classpath problem: fail the build with a clear message
        throw new IllegalStateException("ANTLR tool installation corrupted; see stderr above", e);
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of antlr/antlr4@7d5770395b (2026-08-14). Data as JSON: /api/errors/682ccdd138a1322b. Report an issue: GitHub.