Ktor 3.3.2: UserAgent ClassNotFoundException With R8

Dec 6, 2025 by Alex Johnson 53 views

Facing a ClassNotFoundException for the UserAgent plugin when using Ktor 3.3.2 with R8 enabled can be a real headache. This article dives into the specifics of this issue, offering insights, potential solutions, and workarounds to help you navigate this problem effectively. We'll explore the error, its causes, reproduction steps, and possible fixes, ensuring your Ktor-based Android applications run smoothly even with R8's optimizations.

Understanding the Issue

The core problem lies in the ClassNotFoundException that occurs specifically for the io.ktor.client.plugins.UserAgent class. This exception arises when a third-party SDK, such as Moloco SDK, initializes an HttpClient with the UserAgent plugin enabled. The crash manifests primarily in release builds where R8 minification is active. This issue has been observed to affect a significant number of users, particularly on Samsung Galaxy devices, indicating a potential pattern or device-specific interaction. The stack trace clearly points to the inability to resolve the UserAgent class at runtime, suggesting that R8 might be stripping away necessary class definitions despite efforts to preserve them through ProGuard rules. Understanding the root cause involves examining how R8 handles class dependencies and reflection within Ktor's plugin system.

Key factors contributing to this issue include:

R8 Optimization: R8, the code shrinker and optimizer, aggressively removes unused code, which, under certain circumstances, incorrectly identifies the UserAgent plugin as unnecessary.
Ktor Plugin System: The dynamic nature of Ktor's plugin system may complicate R8's ability to correctly identify and preserve all required classes and dependencies.
Third-Party SDKs: The integration of third-party SDKs that initialize HttpClient with the UserAgent plugin can trigger the issue due to indirect class references.

To effectively address this, it's essential to understand how these factors interact and influence the runtime behavior of the application. By examining the R8 configuration, Ktor's internal class references, and the specific usage patterns of the UserAgent plugin within the third-party SDK, developers can gain valuable insights into the underlying cause and implement targeted solutions.

Diagnosing the Problem: Stack Trace and Error Analysis

Let's break down the stack trace to understand the error's origin. The stack trace below highlights the key points where the error occurs:

Fatal Exception: java.lang.NoClassDefFoundError
Failed resolution of: Lio/ktor/client/plugins/UserAgent;

com.moloco.sdk.internal.http.a$a.a (SourceFile:1)
com.moloco.sdk.internal.http.a$a.invoke (SourceFile:1)
io.ktor.client.HttpClientKt.HttpClient (HttpClient.kt:648)
io.ktor.client.HttpClientJvmKt.HttpClient (HttpClientJvm.kt:25)
...

Caused by java.lang.ClassNotFoundException
io.ktor.client.plugins.UserAgent

The Fatal Exception indicates a critical runtime error that leads to application failure. The NoClassDefFoundError specifically means that the class io.ktor.client.plugins.UserAgent was available during compile time but not found during runtime. This usually happens when the class is not included in the final APK due to stripping by tools like R8. The ClassNotFoundException confirms that the class could not be loaded by the classloader.

The sequence of calls in the stack trace provides further clues:

The error originates from within the Moloco SDK (com.moloco.sdk.internal.http.a$a).
The Moloco SDK is attempting to initialize an HttpClient.
The HttpClient initialization process fails because it cannot find the UserAgent class.

This analysis suggests that the Moloco SDK depends on the UserAgent plugin in Ktor, and R8 is removing this plugin during the optimization process. Even though the application itself might not directly use the UserAgent plugin, the transitive dependency introduced by the Moloco SDK is enough to trigger the error. Developers need to ensure that R8 is configured to keep the UserAgent plugin and its dependencies, even if they are only used indirectly.

Furthermore, the fact that this error occurs predominantly on release builds with R8 enabled suggests that debug builds, which typically have R8 disabled or configured less aggressively, do not exhibit this issue. This highlights the importance of thoroughly testing release builds, especially when using code shrinking and optimization tools.

Steps to Reproduce the Bug

To effectively address this issue, reproducing it in a controlled environment is crucial. Here are the steps to reproduce the bug:

Set Up a New Android Project: Start with a clean Android project in Android Studio.

Add Ktor Dependencies: Include the necessary Ktor dependencies in your build.gradle.kts file:

implementation("io.ktor:ktor-client-android:3.3.2")
implementation("io.ktor:ktor-client-content-negotiation:3.3.2")
implementation("io.ktor:ktor-client-logging:3.3.2")
implementation("io.ktor:ktor-client-auth:3.3.2")

Enable R8 Minification: Enable R8 minification in your gradle.properties file:
```
minifyEnabled = true
shrinkResources = true
```

Simulate Third-Party SDK Usage: Include code that simulates the behavior of a third-party SDK (like Moloco SDK) by initializing an HttpClient with the UserAgent plugin. Here’s an example:

import io.ktor.client.*
import io.ktor.client.engine.android.*
import io.ktor.client.plugins.*
import kotlinx.coroutines.runBlocking

fun initializeHttpClient() {
    val client = HttpClient(Android) {
        install(UserAgent) {
            agent = "My Ktor Client"
        }
    }

    runBlocking {
        try {
            // Make a simple request to trigger the client initialization
            client.get("https://example.com")
        } catch (e: Exception) {
            e.printStackTrace()
        } finally {
            client.close()
        }
    }
}

Build a Release APK: Build a release version of your APK by selecting "Build" -> "Build Bundle(s) / APK(s)" -> "Build APK(s)" in Android Studio.
Run the App on a Device: Install the release APK on an Android device (or emulator) and run the app. Ensure the device is running Android 13 or a similar API level.
Observe the Crash: The app should crash with a ClassNotFoundException related to the UserAgent class when the HttpClient is initialized.

By following these steps, you can reliably reproduce the issue and verify potential solutions. This controlled environment allows for focused testing and ensures that any proposed fixes effectively address the problem without introducing new issues.

Potential Solutions and Workarounds

Several strategies can be employed to address the ClassNotFoundException for the UserAgent plugin when R8 is enabled. Here are some potential solutions and workarounds:

Explicitly Keep the UserAgent Class in ProGuard/R8 Rules: Ensure that your ProGuard or R8 rules explicitly keep the UserAgent class and its associated members. Although the original post mentions including -keep class io.ktor.client.plugins.** { *; }, it might not be sufficient due to aggressive optimization. Try a more specific rule:
```
-keep class io.ktor.client.plugins.UserAgent { *; }
-keep class io.ktor.client.plugins.UserAgent$Feature { *; }
```
Also, consider keeping any associated interfaces or enums that the UserAgent class uses.
Keep All Ktor Client Plugins: To ensure that no Ktor plugins are mistakenly stripped, you can add a more general rule to keep all client plugins:
```
-keep class io.ktor.client.plugins.* { *; }
```
This rule ensures that all classes within the io.ktor.client.plugins package are preserved during the R8 optimization process.

Disable Code Optimization for the UserAgent Class: You can try disabling optimization specifically for the UserAgent class to prevent R8 from modifying it:

-optimizations !class/unboxing/enum,!code/simplification/arithmetic,!field/*,!method/*,!class/merging/*
-keepattributes Exceptions,InnerClasses,Signature,Deprecated,SourceFile,LineNumberTable
-keep class io.ktor.client.plugins.UserAgent { *; }

Conditional Keep Rules: If the UserAgent plugin is only used under certain conditions or by specific classes, you can use conditional keep rules to preserve it only when those conditions are met. This approach minimizes the impact on the overall code size.
```
-keep class io.ktor.client.plugins.UserAgent {
    *; 
}
-keep class com.moloco.sdk.** { *; }
```
Downgrade Ktor Version: As mentioned in the original post, downgrading to Ktor 2.3.12 resolves the issue. While this is not an ideal long-term solution, it can serve as a temporary workaround until a proper fix is implemented.
Check R8 Configuration: Review your R8 configuration to ensure that it does not contain any conflicting rules that might inadvertently strip the UserAgent class. Pay attention to any custom configurations or dependencies that might affect R8's behavior.
Report the Issue to Ktor and Moloco SDK: If the issue persists despite these efforts, consider reporting the bug to both the Ktor project and the Moloco SDK developers. Providing detailed information about the issue, including the stack trace, reproduction steps, and environment details, can help them identify and address the root cause.

By systematically applying these solutions and workarounds, you can effectively mitigate the ClassNotFoundException and ensure that your Ktor-based Android applications function correctly with R8 enabled.

Addressing the Questions

Based on the information provided, let's address the questions raised in the original bug report:

Is this a known issue with Ktor 3.3.2? While not explicitly documented as a widespread issue, the symptoms described—ClassNotFoundException for UserAgent with R8 enabled—suggest a potential regression or interaction issue specific to Ktor 3.3.2, especially considering the previous