apache/iceberg · warning · RuntimeException

Interrupted while waiting for idempotent request to complete

Error message

Interrupted while waiting for idempotent request to complete

What it means

While a REST request waited for an idempotent (duplicate) request to finalize, the waiting thread was interrupted; the code restores the interrupt flag and wraps the InterruptedException in this RuntimeException. The server-side idempotency mechanism detected a repeated request and blocked awaiting the original's result, but the wait was cut short.

Solutions

1. Retry the request once the original completes
2. Avoid duplicate concurrent requests with the same idempotency key
3. Check server logs for the shutdown/interruption cause
4. Increase client timeouts so requests are not cancelled mid-wait

// Deduplicate client-side: track in-flight request keys before sending
if (inFlightKeys.contains(idempotencyKey)) {
  waitForKeyCompletion(idempotencyKey);
}

try {
  send(request);
} catch (RuntimeException e) {
  if (e.getMessage().contains("Interrupted while waiting for idempotent request")) {
    retryWithBackoff(request);
  }
}

When it happens

Trigger: Sending a request whose idempotency key matches an in-flight request, then having the waiting thread interrupted inside IdempotencyEntry.awaitFinalization (server shutdown, executor cancellation).

Common situations: REST server graceful shutdown while duplicate requests are pending; client timeouts cancelling handler threads; load-balancer retries hitting in-flight requests.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Interrupted during commit
• Interrupted during tryLock
• Interrupted in call to initialize
• Interrupted in SQL command
• Interrupted in SQL query

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/d352f1e8a8522423. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/CatalogHandlers.java:251

    void finalizeSuccess(Object body) {
      this.responseBody = body;
      this.status = Status.FINALIZED;
      this.latch.countDown();
    }

    void finalizeError(RuntimeException cause) {
      this.error = cause;
      this.status = Status.FINALIZED;
      this.latch.countDown();
    }

    void awaitFinalization() {
      try {
        this.latch.await();
      } catch (InterruptedException ie) {
        Thread.currentThread().interrupt();
        throw new RuntimeException(
            "Interrupted while waiting for idempotent request to complete", ie);
      }
    }

    boolean isExpired() {
      if (this.status != Status.FINALIZED) {
        return false;
      }

      Instant expiry =
          Instant.ofEpochMilli(this.firstSeenMillis).plusMillis(idempotencyLifetimeMillis);
      return Instant.now().isAfter(expiry);
    }
  }

  /**
   * Exception used to avoid retrying commits when assertions fail.
   *

View on GitHub (pinned to 86d9c8fc54)