quarkusio/quarkus · error · IllegalArgumentException

id is missing for category named ${builder.name}

Error message

id is missing for category named ${builder.name}

What it means

CategoryImpl's Builder.build() enforces that every category in a registry catalog carries an id; if builder.id is null it throws IllegalArgumentException including the category's name. Category ids are the keys used to group extensions, so an id-less category is invalid catalog data.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/catalog/CategoryImpl.java:35

 *
 * @see Category#mutable() creates a builder from an existing Category
 * @see Category#builder() creates a builder
 * @see ExtensionCatalogImpl.Builder#getCategories() will use the builder to deserialize
 * @see JsonBuilder.JsonBuilderSerializer for building a builder before serializing it.
 */
@JsonInclude(JsonInclude.Include.NON_DEFAULT)
@JsonPropertyOrder({ "id", "name", "description", "metadata" })
public class CategoryImpl implements Category {

    private final String id;
    private final String name;
    private final String description;
    private final Map<String, Object> metadata;

    private CategoryImpl(Builder builder) {
        this.id = builder.id;
        if (id == null) {
            throw new IllegalArgumentException("id is missing for category named " + builder.name);
        }
        this.name = builder.name;
        this.description = builder.description;
        this.metadata = JsonBuilder.toUnmodifiableMap(builder.metadata);
    }

    @Override
    public String getId() {
        return id;
    }

    @Override
    public String getName() {
        return name;
    }

    @Override
    public String getDescription() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the id field to the offending category in the catalog JSON (the message names the category).
2. If building programmatically, call Builder.id(...) before build().
3. Report the malformed catalog to the registry operator that published it.
4. Validate catalog JSON against the schema before loading (jq check for .id in each category).

Example fix

// before (catalog JSON)
{"categories": [{"name": "Data", "description": "..."}]}
// after
{"categories": [{"id": "data", "name": "Data", "description": "..."}]}

// Before loading a catalog JSON you authored, validate each category has an id:
// jq -e '.categories | all(has("id"))' catalog.json

// Java
try {
    catalog = ExtensionCatalog.mutableFromFile(json);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("id is missing for category")) {
        logger.error("Malformed catalog: " + e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Deserializing/building an extension catalog whose categories JSON array contains an entry with a name but no id field, then calling Builder.build() — e.g. during ExtensionCatalog.mutableFromFile() of a hand-written or corrupt registry catalog.

Common situations: Hand-editing a catalog JSON and dropping the id field; a registry publishing malformed categories; programmatic catalog construction with Builder.name set but Builder.id left null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${e.getMessage()}
• Extra steps left over
• Unknown start character for json value: %s
• Json array ended without ]
• Control characters not allowed in json string

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