quarkusio/quarkus · error · IllegalStateException

Unable to scan config group: ${configGroup}

Error message

Unable to scan config group: ${configGroup}

What it means

The config documentation annotation processor failed while scanning an annotated config group class (@ConfigMapping with nested group semantics). Listeners run during scanConfigGroups to discover the group's properties; any exception they throw is wrapped in this IllegalStateException naming the config group type.

Source

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

        configMappingWithoutConfigRootListeners.add(new JavadocConfigMappingListener(config, utils, configCollector));

        this.configRootListeners = Collections.unmodifiableList(configRootListeners);
        this.configMappingWithoutConfigRootListeners = Collections.unmodifiableList(configMappingWithoutConfigRootListeners);
    }

    public void scanConfigGroups(RoundEnvironment roundEnv, TypeElement annotation) {
        for (TypeElement configGroup : ElementFilter.typesIn(roundEnv.getElementsAnnotatedWith(annotation))) {
            if (isConfigGroupAlreadyHandled(configGroup)) {
                continue;
            }

            debug("Detected annotated config group: " + configGroup, configGroup);

            try {
                DiscoveryConfigGroup discoveryConfigGroup = applyRootListeners(l -> l.onConfigGroup(configGroup));
                scanElement(configRootListeners, discoveryConfigGroup, configGroup);
            } catch (Exception e) {
                throw new IllegalStateException("Unable to scan config group: " + configGroup, e);
            }
        }
    }

    public void scanConfigRoots(RoundEnvironment roundEnv, TypeElement annotation) {
        for (TypeElement configRoot : typesIn(roundEnv.getElementsAnnotatedWith(annotation))) {
            checkConfigRootAnnotationConsistency(configRoot);

            final PackageElement pkg = utils.element().getPackageOf(configRoot);
            if (pkg == null) {
                utils.processingEnv().getMessager().printMessage(Diagnostic.Kind.ERROR,
                        "Element " + configRoot + " has no enclosing package");
                continue;
            }

            if (isConfigRootAlreadyHandled(configRoot)) {
                continue;
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the wrapped 'Caused by' exception — it pinpoints the actual failure (unregistered enum, unresolvable type, etc.).
2. Fix the named config group: check field types are supported config types and enums are properly registered/annotated.
3. Clean and rebuild so the processor sees fully resolvable sources.
4. Register any custom types the scanner must resolve (e.g. ensure enums used in the group are discoverable).
5. If the wrapped error is a Quarkus processor bug, minimize the group and report it upstream.

Example fix

// before: unregistered/odd type in the group
public class MyAppGroup {
    public SomeUnregisteredEnum mode; // scan fails
}

// after: use a supported, registered type
public class MyAppGroup {
    public Mode mode; // enum registered via @Enumerated/config docs scanning
    public enum Mode { FAST, SLOW }
}

// pre-check the group before compiling docs
for (var m : configGroupClass.getDeclaredFields()) {
    if (!isSupportedConfigType(m.getType()))
        throw new IllegalStateException("Unsupported group member type: " + m);
}

static boolean isScannableGroup(Class<?> g) {
    return Arrays.stream(g.getDeclaredFields())
        .allMatch(f -> f.getType().isPrimitive()
            || CONVERTIBLE_TYPES.contains(f.getType())
            || f.getType().isEnum()
            || isConfigGroup(f.getType()));
}

try {
    scanner.scanConfigGroups(roundEnv, annotation);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to scan config group:")) {
        log.error("Fix the config group named in the message; see Caused by for root cause");
    }
    throw e; // build must fail
}

When it happens

Trigger: Compiling code containing a class annotated as a config group where listener processing fails: malformed/unsupported member types, missing generics info, unresolvable nested types, or a listener bug triggered by an unusual mapping annotation layout.

Common situations: A config group with an exotic field type (e.g. raw Optional of a non-convertible type, unregistered enum, recursive group reference); annotation processing running against partially compiled sources after an incomplete build; a Quarkus regression triggered by a specific mapping shape.

Related errors

• Unable to scan config mapping without config root: ${configM
• Unable to scan config root: ${configRoot}
• Unable to parse: ${resolvedModelPath}
• Multiple listeners returned discovery root elements for: ${d
• No listeners returned a discovery root element

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