What causes "Unknown node type: ${token}" in oracle/graal?

Verify the exact simple name against the node class (case-sensitive).

oracle/graal · error · RuleParseError

Unknown node type: ${token}

Error message

Unknown node type: ${token}

What it means

Thrown by RuleParser.parseType when a token starting with an uppercase letter is not found in knownTypes, the map of node types discovered from @MatchableNode-annotated classes during annotation processing. Uppercase-initial tokens are treated as node type names; lowercase ones are captured variable names. An unknown uppercase token therefore means the type was never registered as matchable (or is misspelled).

Source

Thrown at compiler/src/jdk.graal.compiler.processor/src/jdk/graal/compiler/core/match/processor/MatchProcessor.java:188

                    }
                }
                if (peek(")").equals(")")) {
                    next();
                    return descriptor;
                }
                throw new RuleParseError("Too many arguments to " + descriptor.nodeType.nodeClass);
            }
            throw new RuleParseError("Extra tokens following match pattern: " + peek(null));
        }

        private MatchDescriptor parseType(boolean forExpression) {
            TypeDescriptor type = null;
            String name = null;
            if (Character.isUpperCase(peek("node type or name").charAt(0))) {
                String token = next();
                type = knownTypes.get(token);
                if (type == null) {
                    throw new RuleParseError("Unknown node type: " + token);
                }
                if (peek("=").equals("=")) {
                    next();
                    name = next();
                }
                originatingElements.addAll(type.originatingElements);
            } else if (Character.isLowerCase(peek("name").charAt(0))) {
                name = next();
                type = valueType;
            } else {
                throw new RuleParseError("Unexpected token \"%s\" when looking for name or node type", peek(null));
            }
            requiredPackages.add(type.nodePackage);
            if (name != null) {
                if (!capturedNames.contains(name)) {
                    capturedNames.add(name);
                    capturedTypes.add(type);
                } else {

View on GitHub (pinned to a66e9ccd1d)

Solutions

Verify the exact simple name against the node class (case-sensitive).
Ensure the referenced node class is annotated with @MatchableNode so the processor registers it.
If the type lives in another package, check the processor's requiredPackages/scan configuration makes it visible in this compilation.

Example fix

// before
@MatchRule("add(x, y)")  // typo, also parsed as name not type

// after
@MatchRule("Add(x, y)")

Defensive patterns

Strategy: try-catch

Try / catch

Compile-time only. Tooling can map 'Unknown node type: X' to a search for class X and check whether it carries @MatchableNode.

Prevention

Only reference node classes annotated with @MatchableNode in rules.
Use the exact case-sensitive simple name of the node class.
After renaming a node class, update all @MatchRule strings.

When it happens

Trigger: Referencing a node class in @MatchRule that lacks @MatchableNode (or whose declaring class was not scanned in this compilation round), or a simple typo: "add(x, y)" vs "Add(x, y)", "Ad(x, y)". knownTypes.get(token) returning null triggers the error.

Common situations: Matching on a node type from another suite/package not annotated @MatchableNode; renaming a node class and missing a rule; case typos; using a type's fully-qualified name where the simple name is expected.

Related errors

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/826f02596d5b54c5. Report an issue: GitHub.