antlr/antlr4 · critical · RangeError

replace: range invalid: ${from}..${to}(size=${this.tokens.si

Error message

replace: range invalid: ${from}..${to}(size=${this.tokens.size})

What it means

ErrorManager.panic() (ErrorManager.java:311-315) is the terminal failure of the ANTLR tool's own error/reporting machinery: it throws java.lang.Error("ANTLR ErrorManager panic") after the real cause has already been printed to System.err by the preceding rawError call. It is used when the tool cannot trust itself to format messages (corrupted message templates, missing format files) and also backs panic(String) and panic(ErrorType, Object...) for fatal tool errors. Because it throws Error rather than Exception, standard catch(Exception) blocks will not intercept it.

Source

Thrown at runtime/JavaScript/src/antlr4/TokenStreamRewriter.js:96

        this.replace(tokenOrIndex, tokenOrIndex, text, programName);
    }

    /**
     * Replace the specified range of tokens with the supplied text
     * @param {Token | number} from
     * @param {Token | number} to
     * @param {Text} text
     * @param {string} [programName]
     */
    replace(from, to, text, programName = TokenStreamRewriter.DEFAULT_PROGRAM_NAME) {
        if (typeof from !== "number") {
            from = from.tokenIndex;
        }
        if (typeof to !== "number") {
            to = to.tokenIndex;
        }
        if (from > to || from < 0 || to < 0 || to >= this.tokens.size) {
            throw new RangeError(`replace: range invalid: ${from}..${to}(size=${this.tokens.size})`);
        }
        let rewrites = this.getProgram(programName);
        let op = new ReplaceOp(this.tokens, from, to, rewrites.length, text);
        rewrites.push(op);
    }

    /**
     * Delete the specified range of tokens
     * @param {number | Token} from
     * @param {number | Token} to
     * @param {string} [programName]
     */
    delete(from, to, programName = TokenStreamRewriter.DEFAULT_PROGRAM_NAME) {
        if (typeof to === "undefined") {
            to = from;
        }
        this.replace(from, to, null, programName);
    }

View on GitHub (pinned to 7d5770395b)

Solutions

Read the lines printed to System.err immediately BEFORE the 'ANTLR ErrorManager panic' line — they contain the actual cause (e.g. 'installation corrupted ... .stg') and should be fixed first.
If the cause is the corrupted-format message, fix the classpath/jar as per the installation errors (clean re-download, remove shading/minimization, deduplicate resources).
If the cause is an internal tool error, note the ErrorType and grammar location in the preceding message and fix the grammar/tool invocation; report genuine INTERNAL errors to the ANTLR issue tracker with the stack trace.
Pin one consistent antlr4 version across all build plugins and dependencies so the tool's templates always match its code.

Example fix

// before: catching Exception misses this failure
try {
    Tool tool = new Tool(args);
    tool.processGrammarsOnCommandLine();
} catch (Exception e) {          // never catches java.lang.Error
    log.error("antlr failed", e);
}

// after: also catch Error at the outermost tool-invocation boundary
try {
    Tool tool = new Tool(args);
    tool.processGrammarsOnCommandLine();
} catch (Error | Exception e) {  // ErrorManager.panic() throws Error
    log.error("ANTLR tool aborted: {}", e); // real cause is on System.err above
}

Defensive patterns

Strategy: try-catch

Try / catch

// ErrorManager.panic() throws java.lang.Error("ANTLR ErrorManager panic")
// Catch it only at the outermost tool-invocation boundary and always surface preceding stderr
try {
    org.antlr.v4.Tool tool = new org.antlr.v4.Tool(args);
    tool.processGrammarsOnCommandLine();
    if (tool.getNumErrors() > 0) System.exit(1);
} catch (Error e) {
    if ("ANTLR ErrorManager panic".equals(e.getMessage())) {
        // root cause was already printed to System.err by rawError()
        System.err.println("=> ANTLR tool aborted; fix the message printed above (usually a corrupted install/classpath)");
        System.exit(2);
    }
    throw e;
}

Prevention

Remember this Error is a symptom: always read the rawError output printed just before it on System.err.
Wrap ANTLR tool invocations (CLI, Maven/Gradle plugin, embedded Tool) in a top-level catch (Error | Exception) so builds fail with a diagnostic instead of an uncaught Error stack.
Validate the ANTLR installation (jar present, templates intact, single version) before running the tool in production pipelines.
Do not swallow java.lang.Error in library code; handle it only at the process/build boundary.

When it happens

Trigger: Any of the fatal setFormat failures (missing antlr.stg resource, ST load errors in initSTListener, or verifyFormat() failing for the "antlr" format) end in panic(); additionally panics used for unrecoverable tool errors such as INTERNAL errors or missing generated-file writes go through panic(ErrorType,...) -> panic(msg) -> panic(). Constructing a Tool, or hitting a fatal error during code generation, reaches this throw.

Common situations: Users see this after the 'ANTLR installation corrupted' messages above and mistake the Error for the root cause; also surfaces in build logs when the ANTLR Maven/Gradle/CLI tool aborts on an internal error or a corrupted installation, typically wrapping a classpath, jar-integrity, or environment problem.

Related errors

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