[kotlin] fix: enumUnknownDefaultCase's moshi fallback adapters break nullable enum fields

[wiebren]

With enumUnknownDefaultCase=true, the moshi kotlin client registers a com.squareup.moshi.adapters.EnumJsonAdapter with withUnknownFallback for every enum (SerializerHelper.addEnumUnknownDefaultCase). EnumJsonAdapter is not null-safe and is registered bare, so optional enum fields break:

• writing a model whose optional enum is unset throws NullPointerException: value was null! Wrap in .nullSafe() to write nullable values. This includes every JSON request body the generated ApiClient sends;
• reading an explicit null for an enum field throws JsonDataException.

Without the flag, moshi's built-in enum adapter is null-safe, so the flag is a regression for optional enums. Reproduced on current master.

Fix

jvm-common/infrastructure/SerializerHelper.kt.mustache: append .nullSafe() to the registered adapter in both branches (top-level and inline enums).

Tests and samples

• KotlinClientCodegenModelTest#testMoshiEnumUnknownDefaultCaseAdaptersAreNullSafe generates 3_0/enum.yaml with the flag and asserts every registered adapter is wrapped. Fails without the fix.
• kotlin-enum-default-value, the only moshi sample with the flag, gains .nullSafe() on its five adapters.

PR checklist

• Read the contribution guidelines.
• Built the project and updated samples (./bin/generate-samples.sh ./bin/configs/kotlin*.yaml).
• Technical committee: @jimschubert @dr4ke616 @karismann @Zomzog @andrewemery @4brunu @yutaka0m @stefankoppier

---

Summary by cubic

Enabling enumUnknownDefaultCase in the Moshi Kotlin client no longer breaks nullable enum fields. Previously, the fallback EnumJsonAdapter was registered bare, so any null enum value threw a NullPointerException on read and write; the adapters are now wrapped with .nullSafe() in both the top-level and inline enum branches.

Tests

• Adds a generator test asserting every registered enum fallback adapter is null-safe.
• Updates the kotlin-enum-default-value sample to reflect the new .nullSafe() calls.

^{Written for commit ad31766. Summary will update on new commits.}

---

Generated with Claude Code

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[thejeff77]

Confirming the diagnosis: EnumJsonAdapter from moshi-adapters is not null-safe, and registering it per enum class shadows moshi's built-in enum adapter, which is — so turning enumUnknownDefaultCase on breaks every enum property that is not in required.

We hit this in production. It is worth spelling out where it fires, because it is not only a decode problem. The generated ApiClient puts every JSON request body through:

Serializer.moshi.adapter(T::class.java).toJson(content)

That is the outbound path. Any request whose model has a null optional enum throws before it leaves the client. We reverted enabling the flag across our services because of it.

I built and ran both sides rather than reading the diff.

What I ran

• 7.26.0-SNAPSHOT built from source, Amazon Corretto 21.0.8, macOS arm64
• master f201f33b vs this PR 0cb5a0d7
• ./mvnw -B -pl modules/openapi-generator-cli -am -DskipTests package
• generate -g kotlin --additional-properties=enumUnknownDefaultCase=true (moshi default)
• spec with a required inline enum, an optional inline enum, an optional $ref'd enum, and an array of inline enums
• compiled the generated client with its own gradle wrapper and ran assertions against Serializer.moshi

Generated output between the two jars differs only in the four .nullSafe() calls.

master f201f33b

[1-encode-optional-enum-unset]
  expected: no throw; json omits optionalColor/optionalStatus/tags
  actual:   THROW-> java.lang.NullPointerException: value was null! Wrap in .nullSafe() to write nullable values.

[2-decode-explicit-null]
  expected: optionalColor == null and optionalStatus == null
  actual:   THROW-> com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $.optionalColor

[3-decode-unknown-value]
  actual:   OK   -> optionalColor=unknown_default_open_api optionalStatus=unknown_default_open_api

[4-decode-known-value]
  actual:   OK   -> requiredColor=GREEN optionalColor=BLUE optionalStatus=ACTIVE tags=[A, C]

=== FAILURES: 2 ===

this PR 0cb5a0d7

[1-encode-optional-enum-unset]
  actual:   OK   -> json={"id":"w1","requiredColor":"RED"}

[2-decode-explicit-null]
  actual:   OK   -> optionalColor=null optionalStatus=null

[3-decode-unknown-value]
  actual:   OK   -> optionalColor=unknown_default_open_api optionalStatus=unknown_default_open_api

[4-decode-known-value]
  actual:   OK   -> requiredColor=GREEN optionalColor=BLUE optionalStatus=ACTIVE tags=[A, C]

=== FAILURES: 0 ===

Checks 3 and 4 pass on both sides, which is the part I most wanted to see: .nullSafe() wraps the adapter without disturbing the unknown-value fallback the flag exists for.

The new unit test discriminates. It passes on this branch. Applied on top of master with the template left alone, it fails:

[ERROR] KotlinClientCodegenModelTest.testMoshiEnumUnknownDefaultCaseAdaptersAreNullSafe
java.lang.AssertionError: File '.../infrastructure/SerializerHelper.kt'
  does not contain line [.nullSafe())] expected [true] but found [false]

A few things I checked while I was in there

• SerializerHelper.kt.mustache is the only template in the repo that registers an EnumJsonAdapter, and both of its branches are covered by this diff. Nothing else in the kotlin templates needs the same treatment.
• Coverage is broader than the sample suggests. I generated top-level $ref'd enums, inline property enums, array-item enums and enums on nested objects — all get registered, and all get .nullSafe().
• No regression on required fields. An explicit null for a required enum is still rejected, now with Non-null value 'reqEnum' was null at $.reqEnum rather than the moshi-internal message. A missing required enum still gives Required value 'reqEnum' missing at $.

One likely reason this went unnoticed for so long: enumUnknownDefaultCase is not advertised for kotlin at all. It is absent from config-help -g kotlin and from docs/generators/kotlin.md, though it works — I get 0 occurrences for kotlin and 1 for java from the same jar. That is a separate problem from this PR (it traces back to #12970) and I am happy to take it separately.

If it is useful, the reproduction is on a branch: https://github.com/thejeff77/openapi-generator/tree/chore/verify-kotlin-enum-nullsafe-24894/enum-nullsafe-repro — a spec, a short main(), and a README with the exact commands. Nothing there needs to land here.

Thanks for writing this up, @wiebren. The diagnosis and the fix both look right to me. Glad to help move it along — more cases, a runtime test in the samples, or a rebase onto current master, whichever is most useful.

[thejeff77]

@wiebren — this has been sitting for two weeks with green CI and no triage, so here is what has actually worked for me on Kotlin PRs in this repo, in case it is useful.

Tagging the technical committee mostly does not get a response. You did it correctly in the description, but the listed Kotlin members have reviewed almost nothing this year — counting reviews since January: 4brunu 10 (nine of them Swift), jimschubert 1 (not Kotlin), Zomzog 1, and andrewemery / stefankoppier / karismann zero. I tagged the full committee on two of my own PRs and got no committee response either time.

What worked was Slack. On #23444 I tagged the committee, bumped after a week, then heard nothing for six weeks — until @wing328 commented asking me to resolve conflicts and then "PM me via Slack to have this reviewed and merged". It merged the next day. There is a public invite link at the top of the README.

Two things that should make that conversation short:

• You do not need a rebase. The branch is 48 commits behind master but the GitHub API reports mergeable_state: clean — no conflicts. Worth saying up front, since "please rebase" is a common first response and it would cost you another round trip for nothing.
• 7.26.0 is due 2026-09-24. The milestone gets attached at merge, and this PR currently has no label and no milestone, so it is not on anyone's list for the release. Asking explicitly whether it can make 7.26.0 gives the request a deadline.

For whatever it is worth as supporting evidence: I rebuilt both sides and ran the generated clients — details in my earlier comment. The fix is correct and complete, your test genuinely discriminates, and we reverted enabling this flag across our services because of the bug you are fixing. Happy to add a +1 wherever it helps.

[wiebren]

@thejeff77 thanks for rebuilding both sides and running the generated clients; that is more thorough than the PR's own test, and the outbound toJson path is a good catch that the description underplays. Thanks also for the pointers on getting it looked at, and for checking that it still merges cleanly.

The missing enumUnknownDefaultCase entry in kotlin's config-help and docs/generators/kotlin.md is worth its own issue if you are up for filing it.