quarkusio/quarkus · error · IllegalArgumentException

Missing type argument mapping for

Error message

Missing type argument mapping for 

What it means

JandexUtil.mapGenerics resolves a TYPE_VARIABLE in a type hierarchy against a mapping of type-variable identifiers to concrete Types built while walking the class/interface hierarchy. If the identifier is absent from the mapping, the type arguments of the hierarchy could not be resolved and Quarkus throws this IllegalArgumentException. It signals an internal inconsistency: the type being expanded references a type variable that no enclosing parameterized supertype provided an argument for.

Source

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

    private static Type mapGenerics(Type type, Map<String, Type> mapping) {
        switch (type.kind()) {
            case ARRAY:
                ArrayType arrayType = type.asArrayType();
                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

View on GitHub (pinned to e1c734241f)

Solutions

1. Make the class provide concrete type arguments for every type variable in its hierarchy (e.g. class MyRepo implements Repository<MyEntity, Long> instead of raw Repository).
2. Check for raw types in the hierarchy: an erased supertype drops the argument needed to bind the type variable; parameterize it.
3. If writing an extension, ensure the mapping passed to JandexUtil.mapGenerics covers all type-variable identifiers of the declaring type.
4. Reproduce with a minimal class hierarchy and file a Quarkus issue if a concrete hierarchy still fails — this indicates a resolver bug.

Example fix

// before
class MyRepo implements Repository {
}
// after
class MyRepo implements Repository<MyEntity, Long> {
}

static boolean hasBoundTypeVars(org.jboss.jandex.Type t, java.util.Set<String> bound) {
    if (t.kind() == org.jboss.jandex.Type.Kind.TYPE_VARIABLE)
        return bound.contains(t.asTypeVariable().identifier());
    return true;
}

if (type.kind() != Type.Kind.TYPE_VARIABLE || mapping.containsKey(type.asTypeVariable().identifier())) { /* safe to resolve */ }

try { resolveHierarchy(clazz); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Missing type argument mapping")) { /* raw generic hierarchy: parameterize or handle */ } else throw e; }

When it happens

Trigger: Calling a JandexUtil helper that resolves a generic supertype or interface (e.g. resolving getBindingTypes/determineType hierarchy) where a super interface/class is parameterized in a way the walk did not capture, or where a raw/erased supertype loses the argument needed to satisfy a declared type variable.

Common situations: A CDI bean or resource class extends a generic base class without providing the type argument (raw type usage), unusual self-referential generics (e.g. class A<T> extends B<A<T>>), or Quarkus version changes in generic-hierarchy resolution logic being hit by an extension that passes a type containing free type variables.

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
• Illegal type in hierarchy:
• 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/eb66c788ebacf2c6. Report an issue: GitHub.