apache/skywalking · error · IllegalArgumentException

OAL parsing failed with {n} error(s): {errors}

Error message

OAL parsing failed with {n} error(s): {errors}

What it means

OALScriptParserV2 drives ANTLR parsing of an .oal script with a custom OALErrorListener attached (default console listeners removed). After parser.root() completes, any syntax errors collected by the listener are thrown as one IllegalArgumentException carrying all formatted errors (file, line, column). This is the first gate every OAL script passes through, whether at OAP startup or when installing a dynamic OAL rule.

Source

Thrown at oap-server/oal-rt/src/main/java/org/apache/skywalking/oal/v2/parser/OALScriptParserV2.java:119

        OALLexer lexer = new OALLexer(CharStreams.fromReader(reader));

        // Create token stream
        CommonTokenStream tokens = new CommonTokenStream(lexer);

        // Create parser
        OALParser parser = new OALParser(tokens);

        // Add custom error listener to collect detailed error information
        OALErrorListener errorListener = new OALErrorListener(fileName);
        parser.removeErrorListeners(); // Remove default console error listener
        parser.addErrorListener(errorListener);

        // Parse the script
        OALParser.RootContext root = parser.root();

        // Check for syntax errors
        if (errorListener.hasErrors()) {
            throw new IllegalArgumentException(errorListener.getFormattedErrors());
        }

        // Walk the parse tree with V2 listener
        OALListenerV2 listener = new OALListenerV2(fileName);
        ParseTreeWalker walker = new ParseTreeWalker();
        walker.walk(listener, root);

        return new OALScriptParserV2(listener.getMetrics(), listener.getDisabledSources(), fileName);
    }

    /**
     * Get metrics count.
     */
    public int getMetricsCount() {
        return metrics.size();
    }

    /**

View on GitHub (pinned to 102af09b4a)

Solutions

1. Read the formatted errors in the message: each includes file name, line, and column of the offending token; fix the first error first (later ones are often cascades)
2. Compare your rule against working rules in oap-server/server-starter/src/main/resources/oal/*.oal for exact syntax (source expression, optional where-filter, '-->', metric name)
3. Validate the script in a scratch setup or via the dsl-debugging API before deploying to a live OAP
4. If the script was fine before an upgrade, check the changelog for grammar changes between versions

Example fix

// before (OAL, missing '-->' target name)
svc_sla = from Service.sla -->
// after
svc_sla = from Service.sla --> serviceSla;

// Pre-validate a rule string before pushing it via dynamic configuration (pseudocode):
try {
    OALScriptParserV2.parse(script, "preview.oal");
} catch (IllegalArgumentException e) {
    reject("OAL syntax invalid: " + e.getMessage());
}

Catch IllegalArgumentException around the parse call in tooling (CLI, dsl-debugging install handler) and return the formatted errors (file/line/column) to the caller verbatim; let OAP boot fail fast on bad shipped .oal files so misconfiguration is visible.

When it happens

Trigger: A .oal file (core OAL metrics, custom oal/*.oal, or an OAL rule submitted via dynamic configuration / dsl-debugging) contains a grammar violation: missing '-->' or metric name, bad source expression, unbalanced parentheses, stray characters, or misuse of filter/cast syntax.

Common situations: Editing custom OAL files under oap-server/server-starter resources or the dynamic-configuration OAL rule; typos after copy-pasting metric definitions; using grammar features from a newer version on an older OAP; trailing semicolons or comments not supported by the grammar.

Related errors

• MAL expression parsing failed while injecting expPrefix: {}
• MAL expression parsing failed: {} in expression: {}
• filter expression [{}] not found
• Duplicate worker name:{remoteReceiverWorkName}
• Load meter analyzer configs failed

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/9a833bd12299509d. Report an issue: GitHub.