OpenAPITools/openapi-generator · error · IllegalArgumentException

openApiNullable cannot be set with useJackson3

Error message

openApiNullable cannot be set with useJackson3

What it means

Jackson 3 moved to the tools.jackson packages, and the org.openapitools.jackson.nullable (jackson-databind-nullable) helper the openApiNullable option emits is Jackson-2 only — so openApiNullable=true is rejected while useJackson3 is enabled. The guard only fires when the property is present AND Boolean.parseBoolean(toString(value)) is true; openApiNullable=false is explicitly fine.

Source

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

            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) {
            typeMapping.put("file", "kotlin.ByteArray");
            typeMapping.put("binary", "kotlin.ByteArray");
        }

View on GitHub (pinned to fcec517be3)

Solutions

  1. Remove `openApiNullable` or set it explicitly to `false` when using Jackson 3.
  2. Or drop useJackson3 / stay on Jackson 2 (serializationLibrary=jackson without the useJackson3 flag) to keep JsonNullable wrappers.
  3. Purge the option from shared CI config templates before enabling useJackson3.

Example fix

# before
openapi-generator-cli generate -g kotlin --library=jvm-okhttp4 -i api.yaml -p useJackson3=true,openApiNullable=true
# after
openapi-generator-cli generate -g kotlin --library=jvm-okhttp4 -i api.yaml -p useJackson3=true,openApiNullable=false
Defensive patterns

Strategy: validation

Validate before calling

# shell: reject the forbidden combo up front
if [ "$USE_JACKSON_3" = "true" ] && [ "$OPEN_API_NULLABLE" = "true" ]; then
  echo "openApiNullable=true is incompatible with useJackson3=true" >&2; exit 2
fi

Try / catch

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

Prevention

When it happens

Trigger: `-g kotlin -p useJackson3=true,openApiNullable=true`; or jvm-spring-restclient + useSpringBoot4=true (which auto-enables useJackson3, KotlinClientCodegen.java:479-481) while a shared config file still carries openApiNullable: true.

Common situations: Corporate option presets that always pass openApiNullable=true colliding with a Boot 4 / Jackson 3 migration; copy-pasted option lists across generators.

Related errors

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