What causes "Unknown node type ${type}" in quarkusio/quarkus?

Verify you are not mixing Quarkus versions of rest-client-reactive artifacts on the build classpath

quarkusio/quarkus · error · IllegalStateException

Unknown node type ${type}

Error message

Unknown node type ${type}

What it means

The expression parser classifies each parsed node of a ClientHeaderParam value as Verbatim, ConfigName, or Accessible. If a node of any other (unexpected internal) type reaches the header-filler bytecode generator, the build fails with this IllegalStateException. This indicates an internal invariant break, typically only reachable with a framework bug or subclassed parser nodes.

Source

Thrown at extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/MicroProfileRestClientEnricher.java:978

                                valueType)) {
                            throw new RestClientDefinitionException("Method " + headerFillingMethod.declaringClass().toString()
                                    + "#" + headerFillingMethod.name()
                                    + " has an unsupported return type for ClientHeaderParam. " +
                                    "Only String and String[] return types are supported");
                        }
                    } else {
                        if (!isString(valueType)) {
                            throw new RestClientDefinitionException("Method " + headerFillingMethod.declaringClass().toString()
                                    + "#" + headerFillingMethod.name()
                                    + " has an unsupported return type for ClientHeaderParam. " +
                                    "Only String is supported when using complex expressions");
                        }
                    }

                    return new HeaderFillerInfo(valueType, n, supplier);

                } else {
                    throw new IllegalStateException("Unknown node type " + n.getClass().getName());
                }
            }).collect(Collectors.toList());

            AssignableResultHandle headerList = fillHeader.createVariable(List.class);
            fillHeader.assign(headerList, fillHeader.loadNull());
            if (headerFillerInfos.size() == 1) {
                HeaderFillerInfo headerFillerInfo = headerFillerInfos.get(0);
                ResultHandle headerFillerResult = headerFillerInfo.getResultHandleSupplier().get();
                BytecodeCreator notNullBranchTrue = fillHeader.ifNotNull(headerFillerResult).trueBranch();
                Type headerFillerMethodReturnType = headerFillerInfo.getValueType();
                if (isStringArray(headerFillerMethodReturnType)) {
                    // repack array to list
                    ResultHandle asList = notNullBranchTrue.invokeStaticMethod(ARRAYS_AS_LIST, headerFillerResult);
                    notNullBranchTrue.assign(headerList, asList);
                } else if (isString(headerFillerMethodReturnType)) {
                    notNullBranchTrue.assign(headerList, Gizmo.newArrayList(notNullBranchTrue, 1));
                    notNullBranchTrue.invokeInterfaceMethod(LIST_ADD_METHOD, headerList, headerFillerResult);
                } else {

View on GitHub (pinned to e1c734241f)

Solutions

Verify you are not mixing Quarkus versions of rest-client-reactive artifacts on the build classpath
Clean rebuild (./mvnw clean install) to rule out stale generated classes
If reproducible on a clean checkout, file a Quarkus issue with the failing annotation value

Defensive patterns

Strategy: fallback

Try / catch

// Build-time only; if it ever surfaces, treat as a framework bug
try {
    quarkusBuild();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unknown node type")) {
        throw new IllegalStateException("Quarkus internal bug — clean rebuild, then report issue", e);
    }
    throw e;
}

Prevention

Keep all Quarkus rest-client artifacts on the same version (use the Quarkus BOM)
Run ./mvnw clean install when build errors look nonsensical
Do not fork or override internal parser classes

When it happens

Trigger: Only when the node list produced by RestClientAnnotationExpressionParser contains a Node subclass other than Verbatim/ConfigName/Accessible — not reachable from user code with the stock parser.

Common situations: Practically only seen when running a patched/older mix of Quarkus REST client classes or a custom fork; users should not normally hit this.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/aaa7de7dee27b32c. Report an issue: GitHub.