OpenAPITools/openapi-generator · error · IllegalArgumentException

useJackson3 is only supported for the 'native', 'apache-http

Error message

useJackson3 is only supported for the 'native', 'apache-httpclient', 'jersey3', 'restclient', 'resttemplate', and 'webclient' libraries. The Spring libraries also require useSpringBoot4=true.

What it means

Thrown by JavaClientCodegen.processOpts when the useJackson3 option is enabled for a Java client 'library' whose templates have no Jackson 3 support. Only 'native', 'apache-httpclient', 'jersey3', 'restclient', 'resttemplate', and 'webclient' accept useJackson3. The three Spring libraries (restclient, resttemplate, webclient) additionally require useSpringBoot4=true because their Jackson 3 dependency lines only exist on the Spring Boot 4 / Spring 7 template path. The check runs after convertPropertyToBooleanAndWriteBack resolves the flags, so any truthy value ('true', boolean TRUE) in additionalProperties activates it.

Source

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

        final boolean libOkHttpGson = isLibrary(OKHTTP_GSON) || StringUtils.isBlank(getLibrary());
        final boolean libRestAssured = isLibrary(REST_ASSURED);
        final boolean libRestClient = isLibrary(RESTCLIENT);
        final boolean libRestEasy = isLibrary(RESTEASY);
        final boolean libRestTemplate = isLibrary(RESTTEMPLATE);
        final boolean libRetrofit2 = isLibrary(RETROFIT_2);
        final boolean libVertx = isLibrary(VERTX);
        final boolean libWebClient = isLibrary(WEBCLIENT);

        // default jackson unless overridden by setSerializationLibrary
        this.jackson = !additionalProperties.containsKey(CodegenConstants.SERIALIZATION_LIBRARY) ||
                SERIALIZATION_LIBRARY_JACKSON.equals(additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY));
        convertPropertyToBooleanAndWriteBack(CodegenConstants.USE_ONEOF_DISCRIMINATOR_LOOKUP, this::setUseOneOfDiscriminatorLookup);
        convertPropertyToBooleanAndWriteBack(USE_JACKSON_3, this::setUseJackson3);
        convertPropertyToBooleanAndWriteBack(USE_SPRING_BOOT4, this::setUseSpringBoot4);
        if (useJackson3 && (libRestClient || libRestTemplate || libWebClient) && !useSpringBoot4) {
            throw new IllegalArgumentException("useJackson3 for the restclient, resttemplate, and webclient libraries requires useSpringBoot4=true");
        } else if (useJackson3 && !libNative && !libApache && !libJersey3 && !libRestClient && !libRestTemplate && !libWebClient) {
            throw new IllegalArgumentException("useJackson3 is only supported for the 'native', 'apache-httpclient', 'jersey3', 'restclient', 'resttemplate', and 'webclient' libraries. " +
                    "The Spring libraries also require useSpringBoot4=true.");
        }

        if (this.useJackson3) {
            this.applyJackson3Package();
        } else {
            this.applyJackson2Package();
        }

        if(this.useSpringBoot4) {
            setUseJakartaEe(true);
            applyJakartaPackage();
        }

        // override parent one
        importMapping.put("JsonDeserialize", (useJackson3 ? JACKSON3_PACKAGE : JACKSON2_PACKAGE) + ".databind.annotation.JsonDeserialize");

        // RxJava

View on GitHub (pinned to fcec517be3)

Solutions

  1. If you want Jackson 3, switch to a supported HTTP library: --library native (or apache-httpclient, jersey3)
  2. If you must keep restclient/resttemplate/webclient, also pass --additional-properties useSpringBoot4=true
  3. If you must keep an unsupported library (okhttp-gson, feign, ...), remove useJackson3 from additionalProperties and stay on Jackson 2
  4. Check your --config JSON or Gradle 'configOptions' block for a stray useJackson3 entry, not just the CLI flags

Example fix

# before
openapi-generator-cli generate -g java -i petstore.yaml \
  --library okhttp-gson --additional-properties useJackson3=true

# after
openapi-generator-cli generate -g java -i petstore.yaml \
  --library native --additional-properties useJackson3=true

# alternative for Spring stacks
openapi-generator-cli generate -g java -i petstore.yaml \
  --library restclient --additional-properties useJackson3=true,useSpringBoot4=true
Defensive patterns

Strategy: validation

Validate before calling

// Validate java client options before invoking the generator
boolean useJackson3 = Boolean.parseBoolean(String.valueOf(opts.getOrDefault("useJackson3", "false")));
String library = String.valueOf(opts.getOrDefault("library", "okhttp-gson"));
Set<String> jackson3Libs = Set.of("native", "apache-httpclient", "jersey3", "restclient", "resttemplate", "webclient");
boolean useSpringBoot4 = Boolean.parseBoolean(String.valueOf(opts.getOrDefault("useSpringBoot4", "false")));
if (useJackson3 && !jackson3Libs.contains(library)) throw new IllegalArgumentException("useJackson3 unsupported for library=" + library);
if (useJackson3 && (library.equals("restclient") || library.equals("resttemplate") || library.equals("webclient")) && !useSpringBoot4)
    throw new IllegalArgumentException("useJackson3 on " + library + " requires useSpringBoot4=true");

Try / catch

try {
    new DefaultGenerator().opts(clientOpts).generate();
} catch (IllegalArgumentException e) {
    // option-matrix violations surface here; rethrow with the command line used
    throw new IllegalStateException("Generation config rejected: " + String.join(",", args) + " -> " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Running -g java with --library okhttp-gson|feign|retrofit2|jersey2|vertx|google-api-client|resteasy|microprofile|rest-assured and --additional-properties useJackson3=true. Or using --library restclient|resttemplate|webclient with useJackson3=true but without useSpringBoot4=true (the first branch of the same if/else). Also triggered when the option arrives via a Gradle/Maven plugin configOptions block or a JSON/YAML config file passed with --config.

Common situations: Teams upgrading a generated client to Jackson 3 / Java 17 stacks copy the useJackson3=true flag from another project without changing the HTTP library. Others enable useJackson3 on the default okhttp-gson library (library left blank), which is not in the supported set. A third group sets it with Spring libraries while still pinned to Spring Boot 3 via useSpringBoot3 or the default.

Related errors

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