What causes "Unexpected serializationLibrary value: {serializationLibrary}" in OpenAPITools/openapi-generator?

Change the value to jackson, gson, or jsonb exactly (case-insensitive): --additional-properties serializationLibrary=jsonb

OpenAPITools/openapi-generator · error · IllegalArgumentException

Unexpected serializationLibrary value: {serializationLibrary

Error message

Unexpected serializationLibrary value: {serializationLibrary}

What it means

Thrown by JavaClientCodegen.setSerializationLibrary when the serializationLibrary additional property is not one of the Java client generator's supported JSON libraries: 'jackson', 'gson', or 'jsonb' (case-insensitive). The setter is invoked via convertPropertyToStringAndWriteBack(CodegenConstants.SERIALIZATION_LIBRARY, ...) during processOpts, and also directly by user code or the CLI. Any other string is rejected before templates are rendered.

Source

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

        writePropertyBack(JACKSON_PACKAGE, JACKSON2_PACKAGE);
    }

    protected void applyJackson3Package() {
        writePropertyBack(JACKSON_PACKAGE, JACKSON3_PACKAGE);
    }

    public void setSerializationLibrary(String serializationLibrary) {
        if (SERIALIZATION_LIBRARY_JACKSON.equalsIgnoreCase(serializationLibrary)) {
            this.serializationLibrary = SERIALIZATION_LIBRARY_JACKSON;
            this.jackson = true;
        } else if (SERIALIZATION_LIBRARY_GSON.equalsIgnoreCase(serializationLibrary)) {
            this.serializationLibrary = SERIALIZATION_LIBRARY_GSON;
            this.jackson = false;
        } else if (SERIALIZATION_LIBRARY_JSONB.equalsIgnoreCase(serializationLibrary)) {
            this.serializationLibrary = SERIALIZATION_LIBRARY_JSONB;
            this.jackson = false;
        } else {
            throw new IllegalArgumentException("Unexpected serializationLibrary value: " + serializationLibrary);
        }
    }

    public void forceSerializationLibrary(String serializationLibrary) {
        if (this.serializationLibrary != null && !this.serializationLibrary.equalsIgnoreCase(serializationLibrary)) {
            LOGGER.warn("The configured serializationLibrary '{}', is not supported by the library: '{}', switching back to: {}",
                    this.serializationLibrary, getLibrary(), serializationLibrary);
        }
        setSerializationLibrary(serializationLibrary);
    }

    @Override
    public Map<String, Object> postProcessSupportingFileData(Map<String, Object> objs) {
        generateYAMLSpecFile(objs);
        return super.postProcessSupportingFileData(objs);
    }

    @Override

View on GitHub (pinned to fcec517be3)

Solutions

Change the value to jackson, gson, or jsonb exactly (case-insensitive): --additional-properties serializationLibrary=jsonb
Check the accepted list per generator with `openapi-generator-cli config-help -g java` before reusing configs across language targets
If embedding the generator, validate the string against the three constants before calling setSerializationLibrary
Search your --config JSON and CI templates for a stale serializationLibrary key; the CLI flag and the file both feed the same property

Example fix

# before
openapi-generator-cli generate -g java -i api.yaml \
  --additional-properties serializationLibrary=json-b

# after
openapi-generator-cli generate -g java -i api.yaml \
  --additional-properties serializationLibrary=jsonb

Defensive patterns

Strategy: validation

Validate before calling

Set<String> ok = Set.of("jackson", "gson", "jsonb");
String s = (String) opts.get("serializationLibrary");
if (s != null && !ok.contains(s.toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("serializationLibrary must be one of " + ok + ", got: " + s);
}

Try / catch

try {
    codegen.processOpts();
} catch (IllegalArgumentException e) {
    // setSerializationLibrary rejects unknown values before any file is written
    fail("Unsupported serializationLibrary='" + opts.get("serializationLibrary") + "' for -g java; use jackson|gson|jsonb");
}

Prevention

Normalize serializationLibrary to lowercase before injecting it into options
Maintain a per-generator capability matrix (which JSON libs each -g accepts) in your codegen wrapper
Prefer omitting the option to accept the generator default when you have no strong requirement

When it happens

Trigger: Passing --additional-properties serializationLibrary=moshi (or fastjson, gson-typed, kryo, 'JSON-B' with a stray hyphen) to -g java. Also triggered programmatically via clientCodegen.setSerializationLibrary("json-p") in embedded usage, or when a shared config file written for the Kotlin generator ('serializationLibrary=moshi') is reused for -g java.

Common situations: Config files shared across generators: the Kotlin client accepts 'moshi' and 'kotlinx_serialization', so a multi-generator pipeline reuses an incompatible value. Typos like 'jacksom', 'gscon', or 'json-b' (the accepted literal is 'jsonb') are common. Version upgrades also surface this when a previously tolerated value is removed.

Related errors

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