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

Set serializationLibrary to jackson or jsonb exactly: --additional-properties serializationLibrary=jsonb

OpenAPITools/openapi-generator · error · IllegalArgumentException

Unexpected serializationLibrary value: {serializationLibrary

Error message

Unexpected serializationLibrary value: {serializationLibrary}

What it means

Thrown by JavaHelidonServerCodegen.setSerializationLibrary when serializationLibrary for the Helidon server generator is not 'jackson' or 'jsonb' (case-insensitive). Like the Helidon client (error 124), the server templates only wire Jackson and JSON-B, so gson and everything else is rejected during processOpts. If the property is absent the generator falls back to jackson with an INFO log before this switch runs.

Source

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

    @Override
    public String getHelp() {
        return "Generates a Java Helidon Server application.";
    }

    @Override
    public void setPerformBeanValidation(boolean performBeanValidation) {
        throw new UnsupportedOperationException("Not implemented");
    }

    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);
        }
    }

    /**
     * Check if pom file and src directory already exist.
     *
     * @return outcome of test
     */
    @Override
    protected boolean projectFilesExist() {
        Path projectFolder = Paths.get(getOutputTestFolder());
        Path pom = projectFolder.resolve("pom.xml");
        Path buildGradle = projectFolder.resolve("build.gradle");
        Path src = projectFolder.resolve(Paths.get(sourceFolder, invokerPackage.replace('.', File.separatorChar)));
        return (pom.toFile().exists() || buildGradle.toFile().exists()) && src.toFile().exists();
    }
}

View on GitHub (pinned to fcec517be3)

Solutions

Set serializationLibrary to jackson or jsonb exactly: --additional-properties serializationLibrary=jsonb
Or drop the property and take the jackson default (logged as a fallback INFO message)
Validate shared configs against config-help -g java-helidon-server before rollout
For gson-based servers use a different generator (e.g. -g java with a gson-capable library)

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    codegen.processOpts();
} catch (IllegalArgumentException e) {
    // thrown from setSerializationLibrary before any output is written
    throw new BuildFailure("Fix serializationLibrary for java-helidon-server: " + e.getMessage(), e);
}

Prevention

Scope serialization options to generators that demonstrably support them (verify via config-help)
Default to omitting serializationLibrary on Helidon generators (jackson fallback)
Automate a 'generate into temp dir' smoke test for every shared config in CI

When it happens

Trigger: Running -g java-helidon-server with --additional-properties serializationLibrary=gson (or moshi/any unknown string). Passing a config file inherited from -g java. Calling setSerializationLibrary("gson") in embedded usage.

Common situations: Uniform-serialization policies applied across a microservices estate include gson for Android-adjacent modules and break only the Helidon server jobs. Typos or wrong casing like 'JsonB' are accepted (case-insensitive) but 'json-b' with a hyphen is not.

Related errors

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