apache/iceberg · error · IllegalArgumentException

Invalid idempotency lifetime:

Error message

Invalid idempotency lifetime: 

What it means

The REST catalog server failed to parse the idempotency lifetime configuration value into a Duration. setIdempotencyLifetimeFromIso expects an ISO-8601 duration string (e.g. PT30M); any unparseable value throws this IllegalArgumentException. The value comes from server config, so a bad setting breaks catalog handler configuration.

Solutions

1. Use ISO-8601 duration syntax: PT prefix, e.g. PT30S, PT10M, PT1H
2. Remove the property to use the default lifetime
3. Validate the config with Duration.parse in a startup check
4. Check startup logs for the exact offending value and fix the config

Example fix

// before
rest.idempotency.lifetime=30m
// after
rest.idempotency.lifetime=PT30M

String v = config.get("rest.idempotency.lifetime");
if (v != null) {
  try {
    java.time.Duration.parse(v);
  } catch (DateTimeParseException e) {
    throw new IllegalArgumentException("Not an ISO-8601 duration: " + v);
  }
}

try {
  startServer(config);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid idempotency lifetime")) {
    // fix config and restart
  }
}

When it happens

Trigger: Configuring the REST server's idempotency lifetime with a string that Duration.parse() cannot parse as ISO-8601 (e.g. '30m', '3600', '1 hour'); null is allowed and skips the setting.

Common situations: Deployment config mistakes using plain time strings or numbers instead of ISO-8601 duration format; typos such as missing the 'PT' prefix.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

Related errors

• Cannot assume role to sign REST requests because is not…
• Cannot initialize AuthManager implementation
• Failed to create request URI from base
• Invalid scan planning mode
• Received a request with a relative path and no base URI

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

Appendix: source

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

    try {
      T res = action.get();
      entry.finalizeSuccess(res);
      return res;
    } catch (RuntimeException e) {
      entry.finalizeError(e);
      throw e;
    }
  }

  @VisibleForTesting
  static void setIdempotencyLifetimeFromIso(String isoDuration) {
    if (isoDuration == null) {
      return;
    }
    try {
      idempotencyLifetimeMillis = Duration.parse(isoDuration).toMillis();
    } catch (Exception e) {
      throw new IllegalArgumentException("Invalid idempotency lifetime: " + isoDuration, e);
    }
  }

  private static final class IdempotencyEntry {
    enum Status {
      IN_PROGRESS,
      FINALIZED
    }

    private final CountDownLatch latch;
    private final long firstSeenMillis;
    private volatile Status status;
    private volatile Object responseBody;
    private volatile RuntimeException error;

    private IdempotencyEntry(Status status) {
      this.status = status;
      this.latch = new CountDownLatch(1);

View on GitHub (pinned to 86d9c8fc54)