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

Use jackson or jsonb: --additional-properties serializationLibrary=jackson (or jsonb)

OpenAPITools/openapi-generator · error · IllegalArgumentException

Unexpected serializationLibrary value: {serializationLibrary

Error message

Unexpected serializationLibrary value: {serializationLibrary}

What it means

Thrown by JavaHelidonClientCodegen.setSerializationLibrary when the java-helidon-client generator receives a serializationLibrary other than 'jackson' or 'jsonb'. Unlike the generic Java client (error 123), the Helidon client templates do not support gson, so the accepted set here is smaller and case-insensitive. The setter runs during processOpts via convertPropertyToStringAndWriteBack on CodegenConstants.SERIALIZATION_LIBRARY.

Source

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

            }
        }

        return objs;
    }

    public void setCaseInsensitiveResponseHeaders(final Boolean caseInsensitiveResponseHeaders) {
        this.caseInsensitiveResponseHeaders = caseInsensitiveResponseHeaders;
    }

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

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

    @Override
    public String toApiVarName(String name) {
        String apiVarName = super.toApiVarName(name);
        if (reservedWords.contains(apiVarName)) {
            apiVarName = escapeReservedWord(apiVarName);
        }
        return apiVarName;
    }

View on GitHub (pinned to fcec517be3)

Solutions

Use jackson or jsonb: --additional-properties serializationLibrary=jackson (or jsonb)
Remove the serializationLibrary property entirely to accept the generator default
If gson is a hard requirement, generate with -g java --library okhttp-gson instead of java-helidon-client
Run `openapi-generator-cli config-help -g java-helidon-client` to confirm the options this generator accepts before sharing configs

Example fix

# before
openapi-generator-cli generate -g java-helidon-client -i api.yaml \
  --additional-properties serializationLibrary=gson

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

Defensive patterns

Strategy: validation

Validate before calling

// java-helidon-client accepts only jackson or jsonb
String s = (String) opts.get("serializationLibrary");
if (s != null && !Set.of("jackson", "jsonb").contains(s.toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("java-helidon-client supports serializationLibrary=jackson|jsonb only, got: " + s);
}

Try / catch

try {
    new DefaultGenerator().opts(input).generate();
} catch (IllegalArgumentException e) {
    // 'Unexpected serializationLibrary value' — no partial output is produced; fix the option and rerun
    throw new BuildFailure("helidon-client serializationLibrary rejected: " + e.getMessage(), e);
}

Prevention

Scope serialization options per generator, not globally across a monorepo
After switching -g targets, diff the old config against the new generator's config-help output
Treat gson as Java-client-only knowledge; do not assume portability to helidon generators

When it happens

Trigger: Running -g java-helidon-client with --additional-properties serializationLibrary=gson (or moshi, or any non-jackson/jsonb string). Copying a config from -g java where gson was valid and passing it via --config. Programmatically calling setSerializationLibrary("gson") on the Helidon client codegen.

Common situations: Teams standardizing generated clients on gson across a monorepo apply the same additionalProperties to the Helidon generator and hit the narrower support matrix. Also happens after switching a pipeline from -g java --library okhttp-gson to the dedicated Helidon generator while keeping the old serialization settings.

Related errors

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