OpenAPITools/openapi-generator · error · IllegalArgumentException

useJackson3 requires serializationLibrary=jackson

Error message

useJackson3 requires serializationLibrary=jackson

What it means

In processOpts, enabling useJackson3 requires serializationLibrary=jackson because the Jackson 3 templates (tools.jackson packages) only exist for the jackson stack. Thrown as IllegalArgumentException. Trap: with library=jvm-spring-restclient and useSpringBoot4=true, useJackson3 is force-enabled (KotlinClientCodegen.java:479-481), so leaving serializationLibrary at its default moshi — or explicitly choosing gson/kotlinx_serialization — trips this even if you never asked for Jackson 3.

Source

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

        boolean useSpringBoot4 = additionalProperties.containsKey(USE_SPRING_BOOT4)
                && convertPropertyToBooleanAndWriteBack(USE_SPRING_BOOT4);
        if (JVM_SPRING_RESTCLIENT.equals(getLibrary()) && useSpringBoot4 && !isUseJackson3()) {
            setUseJackson3(true);
            additionalProperties.put(USE_JACKSON_3, true);
            applyJackson3Package();
        }

        if (additionalProperties.containsKey(CodegenConstants.SERIALIZATION_LIBRARY)) {
            setSerializationLibrary((String) additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY));
            additionalProperties.put(this.serializationLibrary.name(), true);
        } else {
            additionalProperties.put(this.serializationLibrary.name(), true);
        }

        if (isUseJackson3()) {
            if (this.serializationLibrary != SERIALIZATION_LIBRARY_TYPE.jackson) {
                throw new IllegalArgumentException("useJackson3 requires serializationLibrary=jackson");
            }
            if (additionalProperties.containsKey("openApiNullable")
                    && Boolean.parseBoolean(additionalProperties.get("openApiNullable").toString())) {
                throw new IllegalArgumentException("openApiNullable cannot be set with useJackson3");
            }
            if (!JVM_OKHTTP4.equals(getLibrary()) && !JVM_SPRING_RESTCLIENT.equals(getLibrary())) {
                throw new IllegalArgumentException("useJackson3 is only supported for the jvm-okhttp4 and jvm-spring-restclient libraries at this time.");
            }
            if (JVM_SPRING_RESTCLIENT.equals(getLibrary()) && !useSpringBoot4) {
                throw new IllegalArgumentException("useJackson3 with jvm-spring-restclient requires useSpringBoot4=true.");
            }
        }

        if (additionalProperties.containsKey(MAP_FILE_BINARY_TO_BYTE_ARRAY)) {
            setMapFileBinaryToByteArray(convertPropertyToBooleanAndWriteBack(MAP_FILE_BINARY_TO_BYTE_ARRAY));
        }
        additionalProperties.put(MAP_FILE_BINARY_TO_BYTE_ARRAY, mapFileBinaryToByteArray);
        if (mapFileBinaryToByteArray) {

View on GitHub (pinned to fcec517be3)

Solutions

  1. Add `serializationLibrary=jackson` (exact) alongside `useJackson3=true`.
  2. For jvm-spring-restclient + useSpringBoot4=true, remember useJackson3 turns itself on — pair it with serializationLibrary=jackson or stay on Boot 3.
  3. If you need moshi/gson/kotlinx_serialization, keep useJackson3 off (Jackson 2) — that combination is simply unsupported.

Example fix

# before
openapi-generator-cli generate -g kotlin --library=jvm-spring-restclient -i api.yaml -p useSpringBoot4=true
# after
openapi-generator-cli generate -g kotlin --library=jvm-spring-restclient -i api.yaml -p useSpringBoot4=true,serializationLibrary=jackson
Defensive patterns

Strategy: validation

Validate before calling

# shell: enforce the jackson3 ⇒ jackson pairing before running
use_j3="${USE_JACKSON_3:-false}"
sl="${SERIALIZATION_LIBRARY:-moshi}"
if [ "$use_j3" = "true" ] && [ "$sl" != "jackson" ]; then
  echo "useJackson3=true requires serializationLibrary=jackson (currently: $sl)" >&2; exit 2
fi
# also covers the spring-restclient auto-enable:
[ "$LIBRARY" = "jvm-spring-restclient" ] && [ "$USE_SPRING_BOOT4" = "true" ] && sl="jackson"

Try / catch

try {
    DefaultGenerator().opts(clientOptInput).generate()
} catch (e: IllegalArgumentException) {
    throw IllegalStateException("Incompatible kotlin generator options: ${e.message}", e) // do not retry
}

Prevention

When it happens

Trigger: `-g kotlin -p useJackson3=true` without serializationLibrary=jackson (default moshi); `--library=jvm-spring-restclient -p useSpringBoot4=true,serializationLibrary=gson`; programmatic setUseJackson3(true) while moshi remains selected.

Common situations: Upgrading a Spring Boot 3→4 pipeline where the flag flips on automatically; combining options from different README examples; teams assuming useJackson3 is an independent toggle.

Related errors

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