What causes "Could not find registered EnumDefinition for ${name}" in quarkusio/quarkus?

Ensure the enum is a plain Java enum directly used as the property type so the scanner registers it.

quarkusio/quarkus · error · IllegalStateException

Could not find registered EnumDefinition for ${name}

Error message

Could not find registered EnumDefinition for ${name}

What it means

ConfigCollector.getResolvedEnum looks up an EnumDefinition previously registered via registerEnum during scanning; if the enum name was never registered, it throws. The scanner registers enums as it discovers them in config properties, so a lookup miss means a property referenced an enum that was never scanned/registered before being resolved.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/scanner/ConfigCollector.java:87

    }

    public void addResolvedEnum(EnumDefinition enumDefinition) {
        resolvedEnums.put(enumDefinition.qualifiedName(), enumDefinition);
    }

    public boolean isEnum(String className) {
        return isResolvedEnum(className);
    }

    public boolean isResolvedEnum(String className) {
        return resolvedEnums.containsKey(className);
    }

    public EnumDefinition getResolvedEnum(String name) {
        EnumDefinition enumDefinition = resolvedEnums.get(name);

        if (enumDefinition == null) {
            throw new IllegalStateException("Could not find registered EnumDefinition for " + name);
        }

        return enumDefinition;
    }

    public Map<String, EnumDefinition> getResolvedEnums() {
        return resolvedEnums;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();

        sb.append("=======================================================\n");
        sb.append("= Config roots\n");
        sb.append("=======================================================\n\n");

        for (DiscoveryConfigRoot configRoot : configRoots.values()) {

View on GitHub (pinned to e1c734241f)

Solutions

Ensure the enum is a plain Java enum directly used as the property type so the scanner registers it.
If you implement a ConfigAnnotationListener, call registerEnum on the collector for every enum your properties reference.
Upgrade Quarkus — several enum-registration gaps in nested/generic property types have been fixed.
Clean rebuild to rule out partial compilation where the enum's class was not yet visible to the scanner.
If it persists, isolate the property/enum pair from the message and file a Quarkus annotation-processor issue.

Example fix

// before: custom listener forgets registration
onConfigProperty(property) { /* handle property, never register enum */ }

// after
collector.registerEnum(new EnumDefinition(myEnumTypeElement));
onConfigProperty(property) { ... }

Defensive patterns

Strategy: validation

Validate before calling

// ensure every enum used in config properties gets registered before resolution
for (Class<? extends Enum<?>> e : enumsUsedInConfig) {
    if (!collector.getResolvedEnums().containsKey(e.getName()))
        collector.registerEnum(new EnumDefinition(elementUtils.getTypeElement(e.getName())));
}

Type guard

static boolean isRegistered(Collector collector, String enumName) {
    return collector.getResolvedEnums().containsKey(enumName);
}

Try / catch

try {
    EnumDefinition def = collector.getResolvedEnum(name);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Could not find registered EnumDefinition")) {
        log.error("Register the enum before resolving it, or use it directly as a property type");
    }
    throw e;
}

Prevention

Use enums directly as property types so the scanner registers them automatically.
If writing custom listeners/scanners, always call registerEnum before resolving properties.
Keep Quarkus up to date — enum registration gaps get fixed.
Clean build after changes to config class structure.

When it happens

Trigger: Resolving a config property whose type is an enum for which no EnumDefinition was registered — the enum was used in a config class but not encountered/registered during the scan (e.g. enum referenced through an unusual type path, nested/generic usage the scanner didn't traverse, or scan ordering issue), or a custom listener omitted registerEnum.

Common situations: Extension authors with custom scanning logic or custom listeners that skip enum registration; enums referenced indirectly (inside maps/collections of generic types) in older Quarkus versions with known processor gaps; duplicated processor runs where registration state was reset mid-compilation.

Related errors

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