What causes "description not found in the available values." in OpenAPITools/openapi-generator?

Pass one of the exact lowercase strings: "stable", "beta", "experimental", or "deprecated" (the check is case-sensitive and does not trim whitespace).

OpenAPITools/openapi-generator · error · IllegalArgumentException

description not found in the available values.

Error message

description not found in the available values.

What it means

Thrown by Stability.forDescription(String) in openapi-generator-core when the argument does not exactly equal (case-sensitive, no trimming) one of the lowercase descriptions of the Stability enum: "stable", "beta", "experimental", "deprecated". The method is the reverse lookup for the node.js-style stability index attached to generators and features, so any consumer mapping an external string back to the enum hits this when the string is unknown. It is a plain IllegalArgumentException with no echo of the offending input, which makes the cause easy to miss.

Source

Thrown at modules/openapi-generator-core/src/main/java/org/openapitools/codegen/meta/Stability.java:63

    }

    /**
     * Returns a value for this stability index.
     *
     * @return The descriptive value of this enum.
     */
    public String value() {
        return description;
    }

    public static Stability forDescription(String description) {
        for (Stability value : values()) {
            if (value.description.equals(description)) {
                return value;
            }
        }

        throw new IllegalArgumentException("description not found in the available values.");
    }
}

View on GitHub (pinned to fcec517be3)

Solutions

Pass one of the exact lowercase strings: "stable", "beta", "experimental", or "deprecated" (the check is case-sensitive and does not trim whitespace).
Normalize before calling: description == null ? null : Stability.forDescription(description.trim().toLowerCase(Locale.ROOT)).
If you cannot trust the input, guard with Arrays.stream(Stability.values()).noneMatch(v -> v.value().equals(desc)) and fall back to a default or reject with your own error naming the bad value.
On mismatch, include the offending value and the valid set in your own error message; the stock message does not echo the input.

Example fix

// before
Stability s = Stability.forDescription(userInput); // "Stable" -> IllegalArgumentException

// after
Stability s = Arrays.stream(Stability.values())
        .filter(v -> v.value().equals(userInput == null ? null : userInput.trim().toLowerCase(Locale.ROOT)))
        .findFirst()
        .orElseThrow(() -> new IllegalArgumentException(
                "Unknown stability '" + userInput + "'. Valid: stable, beta, experimental, deprecated"));

Defensive patterns

Strategy: validation

Validate before calling

boolean known = description != null && Arrays.stream(Stability.values())
        .anyMatch(v -> v.value().equals(description.trim().toLowerCase(Locale.ROOT)));
if (!known) {
    throw new IllegalArgumentException("Unknown stability '" + description
            + "'. Valid values: stable, beta, experimental, deprecated");
}

Type guard

// Java 'type guard' for the stability description vocabulary
public static boolean isStabilityDescription(String s) {
    if (s == null) return false;
    String norm = s.trim().toLowerCase(Locale.ROOT);
    return norm.equals("stable") || norm.equals("beta")
            || norm.equals("experimental") || norm.equals("deprecated");
}

Try / catch

try {
    Stability s = Stability.forDescription(raw);
} catch (IllegalArgumentException e) {
    // message does not echo the input; log raw and the valid set yourself
    LOG.warn("Ignoring unknown stability '{}' (valid: stable, beta, experimental, deprecated)", raw);
    Stability s = Stability.STABLE; // explicit fallback decision
}

Prevention

Treat the stability vocabulary as a fixed enum contract: stable, beta, experimental, deprecated — all lowercase.
Normalize user input (trim + lowercase Locale.ROOT) before calling forDescription.
Never pass raw external strings (config, JSON, CLI args) directly into the reverse lookup.
When adding a new stability level across versions, keep writers and readers on the same openapi-generator version.

When it happens

Trigger: Calling Stability.forDescription("Stable"), forDescription("STABLE"), forDescription(" experimental") (leading/trailing whitespace), or any string not in the set. Passing null also ends here because equals never matches, and the loop falls through to the throw. Typical call sites read the stability string from generator metadata, JSON/YAML config, or user-supplied filter options (e.g. Generators API filtering by stability).

Common situations: Tooling built on openapi-generator that lets users type a stability filter; upgrading openapi-generator versions where a new stability level (e.g. "deprecated" added later) is written by a newer version but read by an older one; locale-specific casing ("Stable" in en-US UIs); parsing the stability value out of a markdown/docs table that capitalizes it.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/cfe57327df615bde. Report an issue: GitHub.