quarkusio/quarkus · error · IllegalStateException

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

Error message

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

What it means

Identical to the ConfigRoot.merge failure but inside ConfigSection.merge: while merging a nested section's items, an item was neither a ConfigSection nor a ConfigProperty, so the exhaustive pattern-match chain fell through and threw. Signals an invalid item inside a config section's item list.

Source

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

    /**
     * This is used to merge ConfigRoot when generating the AsciiDoc output.
     */
    public void merge(ConfigSection other, Map<String, ConfigSection> existingConfigSections) {
        this.generated = this.generated || other.generated;

        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);
    }

    @Override
    public boolean hasDurationType() {
        for (AbstractConfigItem item : items) {
            if (item.hasDurationType() && !item.isDeprecated()) {
                return true;
            }
        }
        return false;
    }

    @Override
    public boolean hasMemorySizeType() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Align Quarkus versions across all modules and run a clean build.
2. Remove stale generated quarkus-config-docs models and rebuild.
3. Use the class name in the message to find the unexpected item's origin and fix its construction site.
4. If extending the model in a fork, add the matching instanceof branch to ConfigSection.merge.

Example fix

// before
} else {
    throw new IllegalStateException("Unknown item type: " + otherItem.getClass());
}

// after (fork with a new item type)
} else if (otherItem instanceof ConfigDeprecation deprecation) {
    this.items.add(deprecation);
} else {
    throw new IllegalStateException("Unknown item type: " + otherItem.getClass());
}

// validate every section's items before merging
for (ConfigSection s : root.getSections()) {
    if (!s.getItems().stream().allMatch(i -> i instanceof ConfigSection || i instanceof ConfigProperty))
        throw new IllegalArgumentException("unexpected item in section " + s.getName());
}

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

When it happens

Trigger: mergeModel -> ConfigRoot.merge -> ConfigSection.merge where a section's items contain an object of an unrecognized class — new model item subtype not handled in merge, or a model JSON deserialized into an unexpected item type.

Common situations: Version-skew across modules in a multi-module Quarkus build (one module's processor wrote a newer model format); custom subclasses of model items; corrupted regenerated docs 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/620112d446086e4d. Report an issue: GitHub.