OpenAPITools/openapi-generator · error · RuntimeException

Invalid microprofileFramework '{microprofileFramework}'. Mus

Error message

Invalid microprofileFramework '{microprofileFramework}'. Must be 'kumuluzee' or none.

What it means

Thrown by JavaClientCodegen.processOpts when the microprofileFramework additional property is present but the resolved microprofileFramework field is not 'kumuluzee' (the only framework the Java microprofile templates ship). The guard runs before convertPropertyToStringAndWriteBack, so it validates the framework choice at generation time; 'kumuluzee' or omitting the property entirely are the only passing states.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java:464

        if (libWebClient && (useSealedOneOfInterfaces || useJakartaEe)) {
            writePropertyBack(JAVA_17, true);
        }

        if (libMicroprofile && useSealedOneOfInterfaces) {
            writePropertyBack(JAVA_17, true);
        }

        if (!useRxJava && !useRxJava2 && !useRxJava3) {
            additionalProperties.put(DO_NOT_USE_RX, true);
        }

        // Java Play
        convertPropertyToBooleanAndWriteBack(USE_PLAY_WS, this::setUsePlayWS);

        // Microprofile framework
        if (additionalProperties.containsKey(MICROPROFILE_FRAMEWORK)) {
            if (!MICROPROFILE_KUMULUZEE.equals(microprofileFramework)) {
                throw new RuntimeException("Invalid microprofileFramework '" + microprofileFramework + "'. Must be 'kumuluzee' or none.");
            }
//            this.setMicroprofileFramework(additionalProperties.get(MICROPROFILE_FRAMEWORK).toString());
        }
        convertPropertyToStringAndWriteBack(MICROPROFILE_FRAMEWORK, this::setMicroprofileFramework);

        convertPropertyToBooleanAndWriteBack(MICROPROFILE_GLOBAL_EXCEPTION_MAPPER, this::setMicroProfileGlobalExceptionMapper);
        convertPropertyToBooleanAndWriteBack(MICROPROFILE_REGISTER_EXCEPTION_MAPPER, this::setMicroProfileRegisterExceptionMapper);

        additionalProperties.put(MICROPROFILE_REGISTER_EXCEPTION_MAPPER, microProfileRegisterExceptionMapper);
        additionalProperties.put(MICROPROFILE_GLOBAL_EXCEPTION_MAPPER, microProfileGlobalExceptionMapper);

        convertPropertyToBooleanAndWriteBack(MICROPROFILE_MUTINY, this::setMicroprofileMutiny);

        convertPropertyToStringAndWriteBack(MICROPROFILE_REST_CLIENT_VERSION, value -> microprofileRestClientVersion = value);
        if (!mpRestClientVersions.containsKey(microprofileRestClientVersion)) {
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT,
                            "Version %s of MicroProfile Rest Client is not supported or incorrect. Supported versions are %s",

View on GitHub (pinned to fcec517be3)

Solutions

Set the value exactly to kumuluzee: --additional-properties microprofileFramework=kumuluzee
If you do not specifically need KumuluzEE support, delete the microprofileFramework property and rely on the default
For Helidon MP or OpenLiberty targets, use their dedicated generators (-g java-helidon-server / --library open-liberty on -g jaxrs-jersey) instead of this option
Check for case sensitivity: 'Kumuluzee' is rejected; the comparison is exact

Example fix

# before
openapi-generator-cli generate -g java -i api.yaml \
  --library microprofile --additional-properties microprofileFramework=helidon

# after
openapi-generator-cli generate -g java -i api.yaml \
  --library microprofile --additional-properties microprofileFramework=kumuluzee

Defensive patterns

Strategy: validation

Validate before calling

Object fw = opts.get("microprofileFramework");
if (fw != null && !"kumuluzee".equals(String.valueOf(fw))) {
    throw new IllegalArgumentException("microprofileFramework must be 'kumuluzee' or absent, got: " + fw);
}

Try / catch

try {
    CodegenConfig config = CodegenConfigLoader.forName("java");
    config.additionalProperties().putAll(opts);
    new DefaultGenerator().opts(new ClientOptInput()).config(config).generate();
} catch (RuntimeException e) {
    // catches the 'Invalid microprofileFramework' RuntimeException from processOpts
    log.error("Bad microprofileFramework option: {}", opts.get("microprofileFramework"), e);
    throw e;
}

Prevention

Whitelist exact enum-like option values in your config loader instead of passing strings through
Before adopting an option, confirm its accepted values from the generator's docs or config-help output
Avoid carrying options between generators when copying config files

When it happens

Trigger: Passing --additional-properties microprofileFramework=<anything other than kumuluzee> (e.g. helidon, open-liberty, quarkus, empty string) with -g java --library microprofile. Also triggered when a config file (--config config.json) contains a "microprofileFramework" key with an arbitrary value, or a Gradle plugin configOptions block carries it over from an old project.

Common situations: Developers assume microprofileFramework selects any MicroProfile implementation server and try to target Helidon MP or OpenLiberty through the Java client generator. Others copy a kumuluzee-specific config to a newer generator version where the accepted value set never grew, or typo the value ('Kumuluzee', 'kumuluz').

Related errors

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