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

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.

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.

Appendix: 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)