What causes "Unknown library option %s for Helidon Server" in OpenAPITools/openapi-generator?

Pick one of the two supported flavors: --library helidon-mp or --library helidon-se

OpenAPITools/openapi-generator · error · IllegalArgumentException

Unknown library option %s for Helidon Server

Error message

Unknown library option %s for Helidon Server

What it means

Thrown by JavaHelidonServerCodegen.processOpts when the selected --library is neither 'helidon-mp' nor 'helidon-se', the only two flavors the Helidon server generator implements. The else-branch fires after isLibrary(HELIDON_MP) and isLibrary(HELIDON_SE) both miss, and it logs the offending value via LOGGER.error before throwing. Note the dedicated java-helidon-server generator exists precisely to hold these two flavors; other Helidon server styles belong to different generators.

Source

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

                importMapping.put("ByteArrayOutputStream", "java.io.ByteArrayOutputStream");
                importMapping.put("DataChunk", "io.helidon.common.http.DataChunk");
                importMapping.put("UncheckedIOException", "java.io.UncheckedIOException");
                importMapping.put("IOException", "java.io.IOException");
                importMapping.put("ByteArrayInputStream", "java.io.ByteArrayInputStream");
            }
            importMapping.put("Map", "java.util.Map");
            importMapping.put("ReadableBodyPart",  // use the old ReadableBodyPart name for backward compatibility
                    (helidonMajorVersion <= 3)
                            ? "io.helidon.media.multipart.ReadableBodyPart"
                            : "io.helidon.http.media.multipart.ReadablePart");
            importMapping.put("Handler", "io.helidon.webserver." + (helidonMajorVersion != 3 ? "http." : "") + "Handler");
            importMapping.put("GenericType", "io.helidon.common.GenericType");
            importMapping.put("GenericTypes", modelPackage + ".GenericTypes");
            importMapping.put("Optional", "java.util.Optional");
            processSupportingFiles(modifiable, unmodifiable);
        } else {
            LOGGER.error("Unknown library option (-l/--library): {}", getLibrary());
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT,
                            "Unknown library option %s for Helidon Server",
                            getLibrary()
                    )
            );
        }

        if (getSerializationLibrary() == null) {
            LOGGER.info("No serializationLibrary configured, using '{}' as fallback", SERIALIZATION_LIBRARY_JACKSON);
            setSerializationLibrary(SERIALIZATION_LIBRARY_JACKSON);
        }
        switch (getSerializationLibrary()) {
            case SERIALIZATION_LIBRARY_JACKSON:
                additionalProperties.put(SERIALIZATION_LIBRARY_JACKSON, "true");
                additionalProperties.remove(SERIALIZATION_LIBRARY_JSONB);
                supportingFiles.add(new SupportingFile("RFC3339DateFormat.mustache", invokerFolder, "RFC3339DateFormat.java"));
                if (isLibrary(HELIDON_SE)) {
                    supportingFiles.add(new SupportingFile("jsonProvider.mustache",

View on GitHub (pinned to fcec517be3)

Solutions

Pick one of the two supported flavors: --library helidon-mp or --library helidon-se
If your config came from jaxrs-jersey, remove its library value and set helidon-mp or helidon-se explicitly for this generator
Check `openapi-generator-cli config-help -g java-helidon-server` for the enumerated library values before running
If you intended the JAX-RS-style Helidon server, use -g jaxrs-jersey --library helidon instead

Example fix

# before
openapi-generator-cli generate -g java-helidon-server -i api.yaml \
  --library jersey

# after
openapi-generator-cli generate -g java-helidon-server -i api.yaml \
  --library helidon-se

Defensive patterns

Strategy: validation

Validate before calling

Set<String> helidonServerLibs = Set.of("helidon-mp", "helidon-se");
String library = String.valueOf(opts.getOrDefault("library", ""));
if (!helidonServerLibs.contains(library)) {
    throw new IllegalArgumentException("-g java-helidon-server requires --library helidon-mp|helidon-se, got: '" + library + "'");
}

Try / catch

try {
    new DefaultGenerator().opts(input).generate();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Helidon Server")) {
        throw new ConfigurationException("Set --library helidon-mp or helidon-se for java-helidon-server", e);
    }
    throw e;
}

Prevention

Store per-generator library whitelists in your codegen wrapper and validate before invoking the CLI
When migrating between generators, re-derive --library from the new generator's config-help instead of carrying old values
Add required-option checks (like --library for java-helidon-server) to config templates

When it happens

Trigger: Running -g java-helidon-server --library <default> or --library jersey (or any string). Happens when a config file written for -g jaxrs-jersey --library helidon is reused verbatim with -g java-helidon-server, or when the --library flag is simply forgotten (the generator does not default it here).

Common situations: Migration confusion between the JAX-RS 'jaxrs-jersey' generator (whose library list includes 'helidon') and the dedicated java-helidon-server generator (whose library values are helidon-mp/helidon-se). Copy-pasted CI commands that swap -g but keep the old --library value.

Related errors

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