What causes "Unknown primitive type: ${jandexType}" in quarkusio/quarkus?

Check the actual Jandex type passed; unbox or normalize to a true primitive Kind before calling

quarkusio/quarkus · error · IllegalArgumentException

Unknown primitive type: ${jandexType}

Error message

Unknown primitive type: ${jandexType}

What it means

AsmUtil.getReturnInstruction maps a Jandex primitive type to the corresponding JVM *RETURN opcode (IRETURN, LRETURN, DRETURN, FRETURN). This IllegalArgumentException is thrown from the switch default when the given Jandex Type is a primitive kind the mapper does not recognize (e.g. an unexpected Kind) — effectively a bug/unhandled-case guard in bytecode generation.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/util/AsmUtil.java:145

     * @return the correct bytecode return instruction for that return type descriptor.
     */
    public static int getReturnInstruction(Type jandexType) {
        if (jandexType.kind() == Kind.PRIMITIVE) {
            switch (jandexType.asPrimitiveType().primitive()) {
                case BOOLEAN:
                case BYTE:
                case SHORT:
                case INT:
                case CHAR:
                    return Opcodes.IRETURN;
                case DOUBLE:
                    return Opcodes.DRETURN;
                case FLOAT:
                    return Opcodes.FRETURN;
                case LONG:
                    return Opcodes.LRETURN;
                default:
                    throw new IllegalArgumentException("Unknown primitive type: " + jandexType);
            }
        } else if (jandexType.kind() == Kind.VOID) {
            return Opcodes.RETURN;
        }
        return Opcodes.ARETURN;
    }

    /**
     * Invokes the proper LDC Class Constant instructions for the given Jandex Type. This will properly create LDC instructions
     * for array types, class/parameterized classes, and primitive types by loading their equivalent <tt>TYPE</tt>
     * constants in their box types, as well as type variables (using the first bound or Object) and Void.
     *
     * @param mv The MethodVisitor on which to visit the LDC instructions
     * @param jandexType the Jandex Type whose Class Constant to load.
     */
    public static void visitLdc(MethodVisitor mv, Type jandexType) {
        switch (jandexType.kind()) {
            case ARRAY:

View on GitHub (pinned to e1c734241f)

Solutions

Check the actual Jandex type passed; unbox or normalize to a true primitive Kind before calling
For reference/void/array types use the correct branch — the method already handles VOID and defaults to ARETURN for references, so verify the type is genuinely primitive
Update AsmUtil mapping if a new Jandex Kind must be supported
Add a unit test covering all primitive kinds reaching this method

Example fix

// before
int opcode = AsmUtil.getReturnInstruction(typeFactory.getType(Integer.class)); // CLASS kind -> throws
// after
int opcode = AsmUtil.getReturnInstruction(typeFactory.getType(int.class)); // IRETURN

Defensive patterns

Strategy: validation

Validate before calling

boolean isSupportedPrimitive(io.quarkus.gizmo.gencore... JandexType t) {
    switch (t.kind()) {
        case BOOLEAN: case BYTE: case CHAR: case SHORT:
        case INT: case LONG: case FLOAT: case DOUBLE:
            return true;
        case VOID:
        case CLASS:
            return true; // handled by dedicated branches
        default:
            return false;
    }
}

Try / catch

int opcode;
try {
    opcode = AsmUtil.getReturnInstruction(jandexType);
} catch (IllegalArgumentException e) {
    opcode = org.objectweb.asm.Opcodes.ARETURN; // safe default for reference types
}

Prevention

Confirm the Jandex type is a true primitive before requesting return opcodes
Use type.getName()/kind() checks (INT vs CLASS Integer) before bytecode generation
Update AsmUtil mappings when upgrading Jandex to a version with new kinds
Test generated methods for every primitive return type

When it happens

Trigger: Calling getReturnInstruction with a Jandex Type whose kind() is not one of BOOLEAN/BYTE/CHAR/SHORT/INT/LONG/FLOAT/DOUBLE handled by the switch, e.g. a CLASS, ARRAY or TYPE_VALUE-containing primitive wrapper misclassified, or a new Jandex Kind not yet mapped.

Common situations: Bytecode-generating extensions (record proxies, config mappers) fed types from annotation inspection; mixing up a boxed type (java.lang.Integer) with the Jandex primitive INT; Jandex version upgrades introducing new kinds.

Related errors

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