[BUG][Kotlin] @JsonCreator decode() in non-nullable enums throws on unknown values instead of returning null (regression in 7.19.0)

[davidlj95]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?

Description

Since version 7.19.0, the generated @JsonCreator decode() method for non-nullable Kotlin enums throws IllegalArgumentException on unknown values. In 7.18.0 and earlier, the same method returned null, allowing callers to handle unknown enum values gracefully (e.g. from forward-compatible APIs where new enum values may be added server-side before clients update their specs).

This is a silent breaking change for any consumer that relied on decode() returning null for unrecognized values. There was no mention of this behavioral change in the release notes.

openapi-generator version

Regression introduced in 7.19.0 (works correctly in 7.18.0). Still present in 7.21.0.

OpenAPI declaration file content or url

openapi: "3.0.3"
info:
  title: Test
  version: "1.0"
paths: {}
components:
  schemas:
    ChannelType:
      type: string
      enum:
        - ANDROID
        - IOS
        - WEB

Generation Details

openapi-generator generate -g kotlin -i spec.yaml -o out \
  --additional-properties=library=jvm-spring

Steps to reproduce

1. Generate with openapi-generator 7.18.0 → ChannelType.decode("UNKNOWN") returns null
2. Generate with openapi-generator 7.19.0 → ChannelType.decode("UNKNOWN") throws IllegalArgumentException

Expected: decode() returns null for unknown values (or at minimum, the breaking change is documented and opt-in).

Actual: decode() throws, breaking any downstream code that handled null gracefully.

Related issues/PRs

• [kotlin-client] Fix enum @JsonCreator to throw for unknown values instead of null, fixes #22662 #22663 — the PR that introduced this change (merged into 7.19.0)

Suggest a fix

Either:

1. Revert to the previous behavior (return null) — this requires removing @JsonCreator from decode(), otherwise there's an inconsistency where Jackson deserialization throws on unknown values but calling decode() directly would return null. Without @JsonCreator, Jackson's default enum handling applies and decode() remains a standalone utility.
2. Make the throwing behavior opt-in via a configuration flag
3. This changes the public API contract of generated models — if kept intentionally, it warrants a major version bump (8.0.0), not a patch/minor release, since consumers rely on the return type and nullability semantics of generated code.

[wing328]

cc @limoneren who's the author of #22663

[limoneren]

Hi, thanks for the write-up. Let me explain my thinking.

There were really two behaviours tied together by PR #22535 (7.18.0):

1. decode() as a function: return type was nullable, KDoc said "null otherwise."
2. Jackson deserialization: before 7.18.0, Jackson didn't use decode() at all. It used its own default handling, which
   throws on unknown values. PR fix(kotlin): add JsonCreator/JsonValue to Jackson enums #22535 added @JsonCreator, which silently rewired Jackson to call decode() -> so Jackson started returning null for unknown values, even for non-nullable Kotlin fields. That's the silent regression I was fixing.

My PR restored Jackson's pre-7.18 throwing behavior. You're correct that, as a side effect, the function decode() itself now
throws for unknown values (when Jackson is used) instead of returning null.

A few things I considered while implementing those changes:

• I searched the codebase and found no tests that ever covered the "decode returns null on unknown" behavior, no generated sample code that calls decode() directly, and no documentation that recommends decode() for handling unknown values. The null-returning behavior was incidental, not a tested or documented contract.
• The supported, documented path for forward-compatibility, exactly the scenario you describe (server adds enum cases before clients update), has always been enumUnknownDefaultCase, which my PR continues to support. Enabling it gives you graceful fallback without silent nulls.
• Java client and kotlin-spring both throw on unknown enum values. The fix brings kotlin-client back in line with the rest of the project.
• A silent null deserialized into a non-nullable Kotlin field crashes later with an NPE far from the actual bad data;
  throwing fails fast at the source.

That said, I'd propose a follow-up PR that adds a decodeOrNull() helper for manual callers who want the old behavior. Idiomatic Kotlin (toIntOrNull, firstOrNull, etc.), and gives anyone affected by 7.19 a one-line migration: MyEnum.decode(x) -> MyEnum.decodeOrNull(x).

That cleanly separates the two contracts and addresses your concern without giving up the Jackson fix. Happy to open the PR if the approach is agreed @wing328 @davidlj95

[davidlj95]

Hi @limoneren thanks for the explanation, super well explained 🔝

Hi, thanks for the write-up. Let me explain my thinking.
A few things I considered while implementing those changes:

• I searched the codebase and found no tests that ever covered the "decode returns null on unknown" behavior, no generated sample code that calls decode() directly, and no documentation that recommends decode() for handling unknown values. The null-returning behavior was incidental, not a tested or documented contract.

Interesting! It's a bit odd though :S As despite incidental, it was documented in KDoc to be the expected (though maybe incidental) behavior as you mentioned

• The supported, documented path for forward-compatibility, exactly the scenario you describe (server adds enum cases before clients update), has always been enumUnknownDefaultCase, which my PR continues to support. Enabling it gives you graceful fallback without silent nulls.

Indeed we should use that for that scenario 💯

• Java client and kotlin-spring both throw on unknown enum values. The fix brings kotlin-client back in line with the rest of the project.

Makes sense!

That said, I'd propose a follow-up PR that adds a decodeOrNull() helper for manual callers who want the old behavior. Idiomatic Kotlin (toIntOrNull, firstOrNull, etc.), and gives anyone affected by 7.19 a one-line migration: MyEnum.decode(x) -> MyEnum.decodeOrNull(x).

That'd be super! For viz, we created one in our projects that looks like this:

inline fun <reified T : Enum<T>> decodeOrNull(data: Any?): T? =
  data?.let { d ->
    enumValues<T>().firstOrNull { entry -> d == entry || "$d".equals("$entry", ignoreCase = true) }
  }

Though that one is generic for any enum as we wanted a quick fix we could use for all generated types around.

That cleanly separates the two contracts and addresses your concern without giving up the Jackson fix. Happy to open the PR if the approach is agreed @wing328 @davidlj95

Agree with that 👍 For the next time though, I think the change could have been a major one. Given this is a breaking change despite the behavior being incidental. But not sure about implications of major release in this project or whether there's a release calendar... Though also was thinking that if we could introduce something in release notes about this it'd be great to find out about this faster.

Thanks a lot again 💪