kotlinx.serialization 1.12.0で変わった例外の型が1.13.0で元に戻った|catchの見直し方と、1.13.0に残る入れ子の上限
kotlinx.serialization 1.13.0は、1.12.0で変えた例外の扱いを元に戻した
JetBrainsのKotlinチームが、2026年11月11日(日本時間12日)にkotlinx.serializationの1.13.0を公開しました(1.13.0のリリースノート)。kotlinx.serializationは、KotlinのクラスとJSONなどを相互に変換する公式のライブラリです。
1.13.0の中心は、1.12.0(10月19日、日本時間20日公開)で入った例外の変更の取り消しです。1.12.0では、JSONの読み書きの途中で、自作のシリアライザーやクラスのコンストラクターが投げた例外を、ライブラリがJsonDecodingExceptionなどに包んで投げるようになりました。包むとは、元の例外をcauseに入れた別の例外として投げ直すことです。1.13.0のリリースノートは、この変更の影響を小さく見積もっていたとして元に戻したと説明しています。1.12.0のリリースノートの冒頭にも、1.13.0へ上げるよう勧める注意が載っています(1.12.0のリリースノート)。
この記事では、同じ最小のKotlinプロジェクトで1.11.0・1.12.0・1.13.0を切り替え、13通りの失敗でどの例外が届くかを比べました。1.12.0に合わせて書いたcatchを1.13.0でどう直すか、1.13.0に残る入れ子の上限、リリースノートにない変更、上げる前に確かめることを順に説明します。
要点
1.12.0に合わせてcauseを見るようにしたcatchは、1.13.0で自作の例外を受け止められなくなる
1.11.0・1.12.0・1.13.0を、同じコードと同じ入力で比べた結果です。
1.12.0だけ
自作の例外がJsonDecodingExceptionなどに包まれる
元の例外はcauseに入ります。requireやcheckの失敗も同じで、書き出しではJsonEncodingExceptionでした。
1.13.0
1.11.0と同じく、自作の例外がそのまま届く
比べた13通りのうち、入れ子の深さ以外の11通りで1.11.0と同じ型でした。
1.13.0に残る変更
401段以上の入れ子はJsonDecodingException
1.12.0で入った上限です。1.11.0では2万段でStackOverflowErrorになりました。上限はmaxNestingDepthで変えられます。
Kotlinの版
1.11.0から上げるなら、Kotlin 2.2系ではビルドが止まる
1.12.0と1.13.0はKotlin 2.4.10で作られています。1.13.0はKotlin 2.3.20のプロジェクトではビルドでき、2.2.20ではコンパイルエラーになりました。
1.12.0だけ、自作の例外がJsonDecodingExceptionなどに包まれる
比べるために、次のクラスを用意しました。skuは自作のシリアライザーで形式を確かめてInvalidSkuException(自作の例外)を投げ、priceは別のシリアライザーでrequireを使い、クラスのinitでもrequireとcheckで値を確かめます。
class InvalidSkuException(message: String) : RuntimeException(message)
object SkuSerializer : KSerializer<String> {
override val descriptor = PrimitiveSerialDescriptor("Sku", PrimitiveKind.STRING)
override fun deserialize(decoder: Decoder): String {
val v = decoder.decodeString()
if (!v.startsWith("SKU-")) throw InvalidSkuException("SKUの形式が違います: $v")
return v
}
override fun serialize(encoder: Encoder, value: String) {
if (!value.startsWith("SKU-")) throw InvalidSkuException("SKUの形式が違います: $value")
encoder.encodeString(value)
}
}
object PositiveIntSerializer : KSerializer<Int> {
override val descriptor = PrimitiveSerialDescriptor("PositiveInt", PrimitiveKind.INT)
override fun deserialize(decoder: Decoder): Int {
val v = decoder.decodeInt()
require(v >= 0) { "負の値は使えません: $v" }
return v
}
override fun serialize(encoder: Encoder, value: Int) = encoder.encodeInt(value)
}
@Serializable
data class Item(
@Serializable(with = SkuSerializer::class) val sku: String,
val name: String,
@Serializable(with = PositiveIntSerializer::class) val price: Int,
val stock: Int,
) {
init {
require(stock >= 0) { "在庫は0以上: $stock" }
check(name.isNotBlank()) { "名前が空です" }
}
}
このクラスをJson.decodeFromStringなどで読み書きし、投げられた例外のクラスを3つの版で比べました。
| 失敗の場面 | 1.12.0で届く型 | 1.11.0・1.13.0で届く型 |
|---|---|---|
| シリアライザーが自作の例外を投げた | JsonDecodingException | InvalidSkuException |
シリアライザーのrequireが失敗 | JsonDecodingException | IllegalArgumentException |
クラスのinitのrequireが失敗 | JsonDecodingException | IllegalArgumentException |
クラスのinitのcheckが失敗 | JsonDecodingException | IllegalStateException |
| リストの2件目で自作の例外 | JsonDecodingException | InvalidSkuException |
decodeFromJsonElementで自作の例外 | JsonDecodingException | InvalidSkuException |
書き出し(encodeToString)で自作の例外 | JsonEncodingException | InvalidSkuException |
| 必須のフィールドがない | 3版とも MissingFieldException | |
| 知らないキー、数値の欄に文字列、壊れたJSON | 3版とも JsonDecodingException | |
Kotlin 2.4.10・JDK 21のJVMで実行。1.11.0と1.13.0は、この表のすべての場面で同じ型でした。網かけは1.12.0だけで型が変わったところ。
1.12.0で包まれた例外は、causeに元の例外が入り、メッセージにはJSONのどこで失敗したかが付きます。たとえばskuの失敗は次のように届きました。
kotlinx.serialization.json.JsonDecodingException:
Deserialization failed because of 'SKUの形式が違います: X-1' exception in the decoder at path: $.sku
cause = InvalidSkuException
この表の場面のうち、1.12.0だけ型が変わったのは、アプリのコードが投げた例外です。欠けたフィールドや型違いのように、ライブラリ自身が投げる例外は、3つの版で同じ型でした。
JsonDecodingException、JsonEncodingException、MissingFieldExceptionは、どれもSerializationExceptionを継承したクラスです。SerializationException自体はIllegalArgumentExceptionを継承しています。1.12.0では自作の例外がJsonDecodingExceptionに包まれて届くので、catch (e: SerializationException)が自作の例外まで受け止め、catch (e: InvalidSkuException)は当たらなくなりました。逆向きには継承していないので、requireが投げるIllegalArgumentExceptionは、catch (e: SerializationException)には当たりません。
causeを見る1.12.0向けのcatchは、1.13.0で自作の例外を外へ出す
1.12.0に上げたときに、SerializationExceptionで受けてcauseを見る書き方に変えたコードは、1.13.0で受け止められない例外が出ます。3通りの書き方を、3つの版で同じ入力に当てました。
A. 1.12.0に合わせた書き方
SerializationExceptionで受け、causeを見る
1.13.0と1.11.0では、自作の例外、initのrequireとcheckの失敗がcatchを素通りしました。
B. 1.13.0に合わせる書き方
自作の例外を先に受け、次にIllegalArgumentException
1.13.0では、自作の例外と、それ以外の入力のエラー(initのrequireの失敗を含む)に分かれました。checkの失敗は外へ出ます。
C. 版に左右されにくい書き方
causeをたどって自作の例外を探す
自作の例外、型違い、initのrequireの失敗は、3版で同じ結果になりました。
Aの書き方は、1.12.0では次のように動いていました。
// A. 1.12.0 に合わせた書き方
try {
Json.decodeFromString<Item>(text)
} catch (e: SerializationException) {
when (e.cause) {
is InvalidSkuException -> showSkuError()
else -> showJsonError()
}
}
1.13.0では、InvalidSkuExceptionがそのまま投げられるので、このcatchに当たらず、呼び出し元へ抜けます。Androidアプリなら、ほかに受け止める場所がなければアプリが落ちます。initのrequireの失敗もIllegalArgumentExceptionのまま届き、SerializationExceptionのcatchには当たりませんでした。
1.13.0だけを使うなら、Bの書き方にします。自作の例外のあとにSerializationExceptionだけで受ける書き方では、initのrequireの失敗が1.13.0でも外へ出ます。IllegalArgumentExceptionで受けると、SerializationExceptionとrequireの失敗の両方を入力のエラーとして扱えます。
// B. 1.13.0 に合わせる書き方
try {
Json.decodeFromString<Item>(text)
} catch (e: InvalidSkuException) {
showSkuError()
} catch (e: IllegalArgumentException) { // SerializationException と require の失敗
showInputError()
}
1.12.0でBの書き方を使うと、自作の例外も包まれて入力のエラーの側に入りました。ライブラリのように、使う側の版を決められないコードでは、Cの書き方にすると版の違いを吸収できます。
// C. 版に左右されにくい書き方
fun findSkuError(e: Throwable): InvalidSkuException? =
generateSequence(e) { it.cause }.filterIsInstance<InvalidSkuException>().firstOrNull()
try {
Json.decodeFromString<Item>(text)
} catch (e: Exception) {
when {
findSkuError(e) != null -> showSkuError()
e is IllegalArgumentException -> showInputError() // SerializationException と require の失敗
else -> throw e
}
}
BとCのどちらでも、initのcheckの失敗(IllegalStateException)は、1.11.0と1.13.0では外へ出て、1.12.0では入力のエラーとして受け止められました。入力の検証にcheckではなくrequireを使うと、どの版でも入力のエラーとして扱えます。
1.13.0には、401段以上の入れ子を止める上限が残る
1.12.0で入った変更のうち、JSONの入れ子の深さの上限は1.13.0にも残っています(入れ子の深さを数えるプルリクエスト)。既定の上限は400段です。parseToJsonElementで読むと、[を400個重ねた配列は読め、401個でJsonDecodingExceptionになりました。
1.11.0(2万段)
StackOverflowError
Exceptionのcatchには当たらないエラーです。
1.12.0・1.13.0(401段以上)
JsonDecodingException
メッセージの1行目は「Json input is too nested and may be impossible to parse without stack overflow.」で、2行目に今の上限と変え方が出ます。
上限に達する深さは、読み方で変わります。1.13.0で、同じ形の入れ子を型として読むと、オブジェクトを入れ子にした型(ONode?)はJSONの深さ400段まで読めました。Map<String, MNode>を入れ子にした型は267段までで、それより深いとJsonDecodingExceptionになりました。Mapを入れ子にした型を読むアプリは、400段より浅いJSONでも上限に達することがあります。
深すぎるJSONは、ほかのJSONのエラーと同じcatchで受け止められる例外になりました。上限を超える正当なJSONを扱う場合は、Jsonの設定で上限を上げます。この設定は実験的なAPIで、@OptInを付けないとコンパイル時に警告が出ます(手元ではエラーにはならず、ビルドは通りました)。
@OptIn(ExperimentalSerializationApi::class)
val deepJson = Json { maxNestingDepth = 2000 }
この設定では、2000段は読め、2001段でJsonDecodingExceptionになりました。公式の説明(Json.ktのドキュメントコメント)は、既定より上げるときは慎重に試すこと、上げて読めても、作ったJsonElementのtoString()などでスタックオーバーフローが起こりうることを書いています。上限は必要な深さだけ上げ、アプリと同じ環境で、その深さのJSONを読んで試します。
JsonElementとして読むとき、[1]2]のような壊れた配列が1.13.0から例外になる
リリースノートには書かれていませんが、1.13.0には、壊れた配列をJsonElementとして読むときの修正も入っています(配列の読み取りを直したプルリクエスト)。
Json.parseToJsonElement("[1]2]")の結果
- 1.11.0・1.12.0:
[1,2]として読めた({"a":[1]2]}は{"a":[1,2]}) - 1.13.0:
JsonDecodingException(Expected EOF after parsing, but had 2 instead)
decodeFromString<JsonElement>でも同じ結果でした。decodeFromString<List<Int>>のように型を決めて読む場合は、3つの版ともJsonDecodingExceptionでした。正しいJSONの読み方は変わりません。サーバーやテストの入力に、このような壊れた配列が混ざっていて、それをJsonElementとして読んでいた場合だけ、1.13.0から例外になります。
1.13.0に上げる前に確かめる4つのこと
1.12.0から1.13.0に上げると、自作の例外の扱いは1.11.0と同じに戻り、入れ子の上限は残ります。上げる前に、次の4つを確かめます。
上げる前に確かめる4つのこと
- 使っている版を確かめる。下の
dependencyInsightで、実際に使われる版と、どの依存から来たかが分かります。 - 1.11.0以前から上げる場合は、Kotlinの版を確かめる。1.13.0は、Kotlin 2.3.20のプロジェクトではビルドでき(依存の
kotlin-stdlibは2.4.10に上がります)、2.2.20ではコンパイルエラーになりました。1.12.0でビルドできているプロジェクトは、Kotlinの版を変えずに上げられます。 JsonDecodingExceptionやSerializationExceptionのcauseを見ているcatchを探し、BかCの書き方に直す。- 深い入れ子のJSONを読むかを確かめ、読むなら
maxNestingDepthを必要な深さだけ上げて試す(Mapを入れ子にした型は、約270段で上限に達しました)。
Androidアプリのreleaseビルドで使われる版は、次のコマンドで確かめられます。手元のJVMのプロジェクトでは、構成名runtimeClasspathで確かめました。モジュール名がappでない場合や、フレーバーがある場合は、モジュール名と構成名を合わせます。
./gradlew :app:dependencyInsight --dependency kotlinx-serialization-json --configuration releaseRuntimeClasspath
同じライブラリを複数の依存が求めると、Gradleは既定でそのうちいちばん新しい版を選びます。Maven Centralで確かめたところ、Ktor 3.6.1のktor-serialization-kotlinx-jsonは1.11.0、Retrofitのconverter-kotlinx-serialization 3.0.0はcoreの1.8.1に依存していて、どちらも1.12.0を持ち込みません。1.12.0が入っている場合は、自分で1.12.0を書いたか、ほかの依存が持ち込んだかを、このコマンドの出力で見分けます。
1.13.0に上げたら、自作のシリアライザーやクラスのinitで例外を投げる入力をテストに入れておくと、次に例外の扱いが変わったときにも気づけます。
参考資料
- kotlinx.serialization 1.13.0のリリースノート(GitHub、2026年11月11日)
- kotlinx.serialization 1.12.0のリリースノート(2026年10月19日、冒頭に1.13.0を勧める注意)
- 1.12.0と1.13.0の差分(例外の処理を戻す3つのコミット)
- Add Json nesting depth calculation during parsing(#3246)
- Reject values after the closing bracket of an array in parseToJsonElement(#3290)
- Json.kt(1.13.0、maxNestingDepthの説明)
検証環境
- macOS 27.0.1(Apple Silicon)、JDK 21.0.8、Gradle 9.9.0
- Kotlin Gradleプラグイン 2.4.10(互換の確認で2.3.20・2.2.20)、kotlinx-serialization-json 1.11.0・1.12.0・1.13.0
- 検証日: 2026年11月15日
この記事は、AIが調査と下書きを担当し、上記の環境で実際に動かして結果を確かめ、下書きとは別の担当が公開前に本文と出典を確認しています。制作と訂正の方針は編集・訂正方針で公開しています。












