quarkusio/quarkus · error · IllegalArgumentException

Recipe name is required

Error message

Recipe name is required

What it means

QuarkusUpdateRecipe.addRecipe() validates that each recipe map parsed from a rewrite update YAML document has a 'name' entry whose value is a String. If the name key is missing or is not a String, the method throws IllegalArgumentException("Recipe name is required"). This guard exists because rewrite YAML documents may contain non-recipe entries (categories), and downstream processing keys recipes by name.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/project/update/rewrite/QuarkusUpdateRecipe.java:52

    public QuarkusUpdateRecipe addOperation(RewriteOperation operation) {
        this.operations.add(operation);
        return this;
    }

    @SuppressWarnings("unchecked")
    public QuarkusUpdateRecipe addRecipes(List<Object> recipe) {
        for (Object r : recipe) {
            if (r instanceof Map) {
                addRecipe((Map<String, Object>) r);
            }
        }
        return this;
    }

    public QuarkusUpdateRecipe addRecipe(Map<String, Object> recipe) {
        Objects.requireNonNull(recipe, "recipe is required");
        if (!recipe.containsKey("name") || !(recipe.get("name") instanceof String)) {
            throw new IllegalArgumentException("Recipe name is required");
        }
        // some YAML documents might not be recipes. For instance, they could be categories.
        if (!recipe.containsKey("type") || !recipe.get("type").toString().endsWith("/recipe")) {
            return this;
        }
        this.recipes.add(recipe);
        return this;
    }

    public BuildTool getBuildTool() {
        return buildTool;
    }

    public List<RewriteOperation> getOperations() {
        return operations;
    }

    public List<Map<String, Object>> getRecipes() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a top-level 'name' string field to the recipe map/YAML document before passing it to addRecipe.
2. Ensure the name value is a plain string in YAML (quote it if it looks numeric or special).
3. If the document is a category rather than a recipe, add 'type: <x>/recipe' checks or skip it before calling addRecipe.

Example fix

// before
Map<String, Object> recipe = Map.of("type", "org.openrewrite.java.Recipe");
quarkusUpdateRecipe.addRecipe(recipe);
// after
Map<String, Object> recipe = Map.of("name", "com.example.MyRecipe", "type", "org.openrewrite.java.Recipe");
quarkusUpdateRecipe.addRecipe(recipe);

if (recipe == null || !(recipe.get("name") instanceof String name) || name.isBlank()) {
    throw new IllegalArgumentException("Recipe name is required before addRecipe()");
}

static boolean hasStringName(Map<String, Object> recipe) {
    return recipe != null && recipe.get("name") instanceof String s && !s.isBlank();
}

try {
    quarkusUpdateRecipe.addRecipe(recipe);
} catch (IllegalArgumentException e) {
    log.warn("Skipping malformed recipe document: " + e.getMessage());
}

When it happens

Trigger: Calling addRecipe(Map<String, Object> recipe) with a map lacking the "name" key, or where recipe.get("name") is not a String (e.g. a number, list, or nested map). Happens when addRecipes iterates YAML documents that were expected to be recipe definitions.

Common situations: A hand-written or third-party rewrite recipe YAML omits the top-level 'name' field; a YAML document is actually a category (no name) and is fed through addRecipe directly instead of being filtered; YAML quoting/typing makes the name parse as a non-string (e.g. an unquoted numeric name).

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

• quarkus-extension.yaml is empty or contains no object
• Registry '${registryId}' config option '${offering}' must no
• Extra steps left over
• Unknown start character for json value: %s
• name cannot be null

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