quarkusio/quarkus · error · IllegalStateException

Unknown item type: ${otherItem.getClass()}

Error message

Unknown item type: ${otherItem.getClass()}

What it means

During ConfigRoot.merge, an item in the other config root was neither a ConfigSection nor a ConfigProperty, so the merge loop hit the else branch and threw. The documentation model only supports these two item types; this indicates an internal model inconsistency (a new/unknown item subtype, or a corrupted/deserialized model) rather than user configuration being wrong per se.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigRoot.java:90

    public void merge(ConfigRoot other) {
        this.qualifiedNames.addAll(other.getQualifiedNames());

        Map<String, ConfigSection> existingConfigSections = new HashMap<>();
        collectConfigSections(existingConfigSections, this);

        for (AbstractConfigItem otherItem : other.getItems()) {
            if (otherItem instanceof ConfigSection otherConfigSection) {
                ConfigSection similarConfigSection = existingConfigSections.get(otherConfigSection.getPath().property());

                if (similarConfigSection == null) {
                    this.items.add(otherConfigSection);
                } else {
                    similarConfigSection.merge(otherConfigSection, existingConfigSections);
                }
            } else if (otherItem instanceof ConfigProperty configProperty) {
                this.items.add(configProperty);
            } else {
                throw new IllegalStateException("Unknown item type: " + otherItem.getClass());
            }
        }

        Collections.sort(this.items);
    }

    private void collectConfigSections(Map<String, ConfigSection> configSections, ConfigItemCollection configItemCollection) {
        for (AbstractConfigItem item : configItemCollection.getItems()) {
            if (item instanceof ConfigSection configSection) {
                configSections.put(item.getPath().property(), configSection);

                collectConfigSections(configSections, configSection);
            }
        }
    }

    public boolean hasDurationType() {
        for (AbstractConfigItem item : items) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Rebuild all modules with the same Quarkus version (mvn clean install) so model and merge logic match.
2. Delete regenerated config-docs model JSON files and rebuild to rule out stale mixed-version models.
3. If you maintain a fork or custom item type, update ConfigRoot.merge to handle it explicitly.
4. Inspect the printed class name (otherItem.getClass()) to identify which item type leaked into the model and where it was created.

Example fix

// before: custom item not handled
this.items.add(new MyCustomItem()); // -> Unknown item type: ...MyCustomItem

// after: extend the model properly or use a supported type
this.items.add(new ConfigProperty(...));

// ensure consistent processor artifacts across modules
assert sameVersion("io.quarkus:quarkus-core", "io.quarkus:quarkus-annotation-processor");
// avoid hand-crafted ConfigRoot items
itemMustBeOneOf(configRoot.getItems(), ConfigSection.class, ConfigProperty.class);

static boolean isMergeable(ConfigItem item) {
    return item instanceof ConfigSection || item instanceof ConfigProperty;
}

When it happens

Trigger: mergeModel merging two ConfigRoots whose items list contains an object that is not ConfigSection or ConfigProperty — e.g. a new item type added to the model without updating merge logic, or a hand-edited/custom-deserialized model JSON containing an unexpected item.

Common situations: Running a snapshot/dev Quarkus version where the model format changed between modules; mixing processor versions across a multi-module build so one jar contributes a model the other's merge code doesn't understand; programmatically constructing or patching config doc models.

Related errors

• Unknown item type: ${otherItem.getClass()}
• Unable to parse: ${resolvedModelPath}
• Multiple listeners returned discovery root elements for: ${d
• No listeners returned a discovery root element
• Could not find registered EnumDefinition for ${name}

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