Announcement: Deprecation of OkHttp connection idle polling

[ianbotsf]

The upcoming v1.8 minor version of the AWS SDK for Kotlin will deprecate the OkHttp engine's connection idle polling feature (OkHttpEngineConfig.connectionIdlePollingInterval). Connection idle polling has been superseded by automatic connection failure retries (OkHttpEngineConfig.retryOnConnectionFailure), which is enabled by default since SDK version v1.6.0. This post details why we're making this change and how to migrate to the preferred solution.

Why was connection idle polling added?

Some AWS services (particularly S3 but generally applies to any web service) may close idle HTTP connections within a very short time—far shorter than the client-side default timeout of 60 seconds. Remote connection closures in OkHttp cannot be detected by callers ahead of time and are only made apparent when attempting to reuse the connection for a subsequent request, which would fail.

To address this problem and increase the success rate of AWS service calls, we added support for connection idle polling in SDK version v1.3.66 and smithy-kotlin version v1.3.18 on 10/31/2024. This opt-in feature allowed users to configure a polling interval via OkHttpEngineConfig.connectionIdlePollingInterval which would periodically test idle connections to see if they were still open remotely. When a connection was closed remotely, this monitoring would detect the problem and remove the connection from the pool, preventing an exception during a future SDK call.

Why is it being deprecated?

Unfortunately, the connection idle polling feature was only ever a workaround for the core problem of detecting remote connection closure. The feature came with a significant downside: users had to choose between a short polling interval (which caused higher resource utilization) and a long polling interval (which reduced overhead but delayed connection acquisition). These tradeoffs and the lack of a sensible default value for the interval made this feature tricky to use and to document.

Since SDK version v1.6.0 and smithy-kotlin version v1.6.0 released on 1/21/2026, the OkHttp engine enables OkHttp's connection failure retry mechanism by default. This HTTP client feature recovers from remote connection closure during connection acquisition without the use of a polling loop or blocking calls, making it more performant and stable than connection idle monitoring.

How to migrate

As mentioned above, the replacement feature retryOnConnectionFailure is already enabled by default. In most cases, the steps to migrate are to verify that retryOnConnectionFailure is not explicitly disabled in your code and then to remove usage of connectionIdlePollingInterval.

For example, if you instantiate an SDK client with connection polling:

S3Client.fromEnvironment {
    httpEngine(OkHttpEngine) {
        connectionIdlePollingInterval = 50.milliseconds
        // ...other settings...
    }
}

Simply remove the connectionIdlePollingInterval setting:

S3Client.fromEnvironment {
    httpEngine(OkHttpEngine) {
        // ...other settings...
    }
}

Deprecation and removal timeline

The connectionIdlePollingInterval feature will become deprecated in SDK minor version v1.8, tentatively scheduled to launch after the release of Kotlin 2.4 which is estimated to be in June or July of 2026. It is targeted for removal in SDK minor version v1.9, tentatively scheduled to launch after the release of Kotlin 2.5.

Feedback

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you encounter a bug with the new retryOnConnectionFailure feature or a problem migrating away from connectionIdlePollingInterval, please file an issue.