Ktor Client and kotlinx.serialization JSON: Typed Response Deserialization Across Client Engines

Answer to the Core Question

When you share a single HttpClient configuration across CIO, OkHttp, Jetty, and Apache engines, the following engine‑specific behaviors must be accounted for to keep typed JSON responses identical:

• Default Content‑Type handling – CIO treats an absent Content‑Type header as application/json. OkHttp and Jetty do not apply this fallback; they throw UnsupportedMediaTypeException or return a raw ByteArray unless the ContentNegotiation plugin is explicitly told to assume JSON.
• Coroutine dispatcher – CIO is coroutine‑native; the request and response processing run on the calling coroutine’s dispatcher. OkHttp and Jetty schedule the I/O on their own thread pools. If your code expects the coroutine to remain cancellable on the original dispatcher, you must wrap the call in withContext(Dispatchers.IO) or configure the engine’s dispatcher via engine { ... }.
• Parameterized type inference – response.receive>() compiles but at runtime the type information is lost, leading to ClassCastException. Callers must supply an explicit KSerializer or KType via typeInfo or serializer.
• Plugin API evolution – Ktor 2.x moved io.ktor.client.plugins.contentnegotiation and changed default content‑type fallback logic. Code written for 1.x may break if the plugin version is not pinned.

Confirmed Facts

• In Ktor 2.3.0, CIO automatically falls back to application/json when the header is missing.
• OkHttp and Jetty require ContentNegotiation to be configured with Json { ignoreUnknownKeys = true } and an explicit defaultContentType(Json) to handle missing headers.
• Using response.receive(typeInfo>()) works uniformly across all engines.
• Coroutine cancellation propagates correctly for CIO; for OkHttp/Jetty you must ensure the engine’s dispatcher is cancellable (e.g., engine { dispatcher = Dispatchers.IO }).

Practical Steps for Identical Deserialization

1. Pin the dependency versions to a specific Ktor 2.x release (e.g., 2.3.0) and to the matching kotlinx-serialization-json version.

   implementation("io.ktor:ktor-client-core:2.3.0")
   implementation("io.ktor:ktor-client-content-negotiation:2.3.0")
   implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.0")
   

2. Configure the plugin with a default content type so that missing headers do not cause failures.

   install(ContentNegotiation) {
       json(Json {
           ignoreUnknownKeys = true
           // other JSON settings
       })
       // Explicitly set the fallback content type
       defaultContentType(ContentType.Application.Json)
   }
   

3. Use explicit serializers for generic types.

   val response: HttpResponse = client.get(url)
   val users: List = response.receive(typeInfo>())
   // or
   val users: List = response.receive(serializer>())
   

4. Handle coroutine dispatching explicitly if needed.

   withContext(Dispatchers.IO) {
       client.get(url) // safe for OkHttp/Jetty
   }
   

5. Add engine‑specific logging to verify which dispatcher is used and whether the default content type is applied.

   client.config {
       engine { /* set dispatcher if required */ }
       install(Logging) { level = LogLevel.ALL }
   }
   

Handling Missing Content‑Type Headers

There is no universal contract across engines. The safest approach is to enforce a default content type in the ContentNegotiation plugin, as shown above. If the server cannot guarantee a Content‑Type, you may also add a request Accept header of application/json to signal the expectation.

Suspension Semantics

CIO’s coroutine‑native I/O means the call never blocks a thread; it suspends on the same dispatcher. OkHttp and Jetty delegate I/O to their own thread pools; if you rely on coroutine cancellation, ensure the engine’s dispatcher is cancellable and that you do not mix blocking calls inside the same coroutine.

Missing Diagnostic Detail

To tailor the configuration precisely, I need to know which engine is currently in use in your HttpClient setup. Please confirm whether you are using CIO, OkHttp, Jetty, or Apache.