quarkusio/quarkus · error · IllegalArgumentException

Illegal type in hierarchy:

Error message

Illegal type in hierarchy: 

What it means

mapGenerics is a closed switch over Jandex Type kinds (ClassType, ParameterizedType, TYPE_VARIABLE, etc.). Encountering a Type kind it does not handle — e.g. an unresolved TypeVariableReference, primitive, wildcard or array type in the hierarchy — throws this IllegalArgumentException. It means Quarkus' generic hierarchy resolver met a type shape it cannot traverse.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/util/JandexUtil.java:280

                return ArrayType.create(mapGenerics(arrayType.constituent(), mapping), arrayType.dimensions());
            case CLASS:
                return type;
            case PARAMETERIZED_TYPE:
                ParameterizedType parameterizedType = type.asParameterizedType();
                Type owner = null;
                if (parameterizedType.owner() != null) {
                    owner = mapGenerics(parameterizedType.owner(), mapping);
                }
                return ParameterizedType.create(parameterizedType.name(),
                        mapGenerics(parameterizedType.arguments(), mapping).toArray(new Type[0]), owner);
            case TYPE_VARIABLE:
                Type ret = mapping.get(type.asTypeVariable().identifier());
                if (ret == null) {
                    throw new IllegalArgumentException("Missing type argument mapping for " + type);
                }
                return ret;
            default:
                throw new IllegalArgumentException("Illegal type in hierarchy: " + type);
        }
    }

    private static ClassInfo fetchFromIndex(DotName dotName, IndexView index) {
        final ClassInfo classInfo = index.getClassByName(dotName);
        if (classInfo == null) {
            throw new ClassNotIndexedException(dotName);
        }
        return classInfo;
    }

    /**
     * Returns the enclosing class of the given annotation instance. For field, method or record component annotations,
     * this will return the enclosing class. For parameters, this will return the enclosing class of the enclosing
     * method. For classes, it will return the class itself. For type annotations, it will return the class enclosing
     * the annotated type usage.
     *
     * @param annotationInstance the annotation whose enclosing class to look up

View on GitHub (pinned to e1c734241f)

Solutions

1. Simplify the hierarchy: replace wildcard or array-typed supertype positions with concrete classes/interfaces.
2. Parameterize wildcards explicitly where the API requires a concrete type argument.
3. Check Jandex/Quarkus version alignment; upgrade Quarkus if a supported type shape is rejected.
4. If writing an extension, pre-filter the types you pass to hierarchy resolution to the supported kinds.

Example fix

// before
class Foo extends Handler<?> {
}
// after
class Foo extends Handler<String> {
}

static boolean isSupportedKind(org.jboss.jandex.Type t) {
    switch (t.kind()) {
        case CLASS: case PARAMETERIZED_TYPE: case TYPE_VARIABLE: return true;
        default: return false;
    }
}

if (type.kind() == Type.Kind.CLASS || type.kind() == Type.Kind.PARAMETERIZED_TYPE || type.kind() == Type.Kind.TYPE_VARIABLE) { /* safe */ }

try { resolve(type); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Illegal type in hierarchy")) { /* unsupported kind: simplify hierarchy or skip */ } else throw e; }

When it happens

Trigger: Resolving the type hierarchy of a class whose supertype chain contains an exotic Type kind (wildcard, array/generic-array, unresolved type-variable reference) rather than ClassType/ParameterizedType/TYPE_VARIABLE.

Common situations: Extensions or generated code that declares hierarchies with wildcard types (Comparable<? extends Foo>) or generic arrays in supertype positions; Jandex version differences producing new Type kinds; bugs in custom extension code that feeds arbitrary types into the resolver.

Related errors

• Couldn't fetch '' class from index
• The following classes were not part of the index and could b
• Our supertype instance does not match supertype declared ar
• Missing type argument mapping for
• Unable to resolve input and output types for handler class <

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