Repository navigation
Add client-v2 retry cause for the TIMEOUT_EXCEEDED server error - #3167
Merged
Merged
Conversation
Server error 159 (TIMEOUT_EXCEEDED) now has a dedicated retry cause, ClientFaultCause.ServerTimeoutExceeded. ServerRetryable does not cover it, and the new cause is not in the default client_retry_on_failures list, so the error is not retried unless a client or an operation enables the cause. Implements: #3072 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Client V2 CoverageCoverage Report
Class Coverage
|
JDBC V2 CoverageCoverage Report
Class Coverage
|
|
JDBC V1 CoverageCoverage Report
Class Coverage
|
Client V1 CoverageCoverage Report
Class Coverage
|
chernser
approved these changes
Sep 30, 2026
chernser
deleted the
polyglot/client-v2-timeout-exceeded-retry-cause
branch
September 30, 2026 02:20
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements #3072.
Server error
159(TIMEOUT_EXCEEDED) gets a dedicated retry cause,ClientFaultCause.ServerTimeoutExceeded:ServerRetryabledoes not cover159anymore.ServerTimeoutExceededis not in the defaultclient_retry_on_failureslist, so159is not retried unless the application enables it. This matches the 0.9.9 behavior and the direction of Port of 0.9.9 patch to main #3147.Client.Builder#retryOnFailures, theclient_retry_on_failuresproperty / JDBC connection property) or for one operation (QuerySettings/InsertSettings#setOption(client_retry_on_failures, List<ClientFaultCause>)). This lets an application retry the timeout for a read but not for an insert without deduplication, as the issue asks.Closes #3072
Design
HttpAPIClientHelper#shouldRetrychecks the code159before theServerRetryablecheck. All three retry loops inClient(query, stream insert, POJO insert) callshouldRetry, so every operation gets the same decision.ServerException.EXECUTION_TIMEOUT = 159is added with the same name and at the same position as in Port of 0.9.9 patch to main #3147. The existingserverExceptionRetryCasestest data gets the same one-line change as Port of 0.9.9 patch to main #3147 (its "retryable" sample becomes code202, because159is no longer retried by default). A trial merge of Port of 0.9.9 patch to main #3147 into this branch is clean in both files, and the tests pass on the merged tree.ServerException#discoverIsRetryableis not changed. Port of 0.9.9 patch to main #3147 removes159from it. Until Port of 0.9.9 patch to main #3147 merges,isRetryable()still returnstruefor159, but the client does not retry it unlessServerTimeoutExceededis configured.Changes
ClientFaultCause: new constantServerTimeoutExceeded(appended).ServerException: new constantEXECUTION_TIMEOUT = 159.HttpAPIClientHelper#shouldRetry:159is retried only forServerTimeoutExceeded.CHANGELOG.md(Breaking Changes, because 0.10.0 retried159by default),docs/releases/0_11_0.md(migration section with client, JDBC and per-operation examples),docs/features.md,docs/integration-client.md.Tests
HttpAPIClientHelperTest#testShouldRetryServerTimeoutExceeded(DataProvider): default list does not retry159;ServerTimeoutExceededdoes (also when theServerExceptionis the cause);ServerRetryabledoes not;ServerTimeoutExceededdoes not retry another retryable code (202);Nonewins overServerTimeoutExceeded.TransportBaseTests#testTimeoutExceededRetriedOnlyForItsFaultCause(WireMock, query / stream insert / POJO insert): default andServerRetryablemake one attempt and throw159;ServerTimeoutExceededretries and succeeds.TransportBaseTests#testTimeoutExceededRetryCausesPerOperation(WireMock, query / stream insert / POJO insert): operation settings enable the retry when the client does not, and disable it when the client does (the operation list replaces the client list).shouldRetrydisabled, 4 of the unit cases fail.Local run in the devbox:
HttpAPIClientHelperTest46/46,TransportBaseTests47/47,ClientTests#testWithOldDefaultspasses. The other failures inClientTests/ClientFailoverTest/ErrorHandlingTestsare the same onmainin this environment (Invalid LZ4 magic bytewith server 26.9, #3105; unreachablelocalhost:8443).Compatibility (
docs/changes_checklist.md)switchoverClientFaultCauseexists;client_retry_on_failuresparsing usesClientFaultCause.valueOf, so the new name parses from the property and the JDBC URL.159is not retried by default anymore; an application that needs the old behavior addsServerTimeoutExceededto the list. Documented inCHANGELOG.mdand the 0.11.0 migration guide.ClientFaultCause.ServerTimeoutExceededandServerException.EXECUTION_TIMEOUTare additive.Checklist
🤖 Generated with Claude Code