apache/iceberg · error · CommitStateUnknownException

Service failed

Error message

Service failed: %s: %s

What it means

Thrown by ViewCommitErrorHandler for HTTP 500/502/503/504 on a view commit. Iceberg wraps a ServiceFailureException in CommitStateUnknownException because the server may or may not have applied the commit — the final state is indeterminate. The caller must not blindly retry as a fresh create; it must reconcile the actual view state first.

Solutions

1. Treat the commit as unknown: reload the view and check whether the change actually landed before retrying
2. Retry the commit only after confirming it was not applied (idempotent retry with same requirements)
3. Check REST service health/logs for the corresponding 5xx cause
4. Add client retry with backoff for transient 502/503/504, and reconcile on 500

Example fix

// before
catalog.updateView(viewId).setSchema(schema).commit(); // 503 -> CommitStateUnknownException
// after
try {
  catalog.updateView(viewId).setSchema(schema).commit();
} catch (CommitStateUnknownException e) {
  View loaded = catalog.loadView(viewId);
  if (!applied(loaded, schema)) {
    catalog.updateView(viewId).setSchema(schema).commit();
  }
}

try {
  updateView.commit();
} catch (CommitStateUnknownException e) {
  View loaded = catalog.loadView(viewId);
  if (!applied(loaded)) {
    updateView.commit(); // safe retry only after confirming not applied
  }
}

When it happens

Trigger: Server-side outages, gateway timeouts, or load-balancer 5xx responses during a view commit request.

Common situations: REST service restart or rolling deploy mid-commit; upstream proxy/gateway 502-504; server overload returning 500.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Failed to remove dropped properties
• failureMessage(planId, response.errorResponse())
• Found unsupported view representations
• View does not exist
• Altering a view is not supported by catalog:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/ErrorHandlers.java:236

    }
  }

  /** View commit error handler. */
  private static class ViewCommitErrorHandler extends DefaultErrorHandler {
    private static final ErrorHandler INSTANCE = new ViewCommitErrorHandler();

    @Override
    public void accept(ErrorResponse error) {
      switch (error.code()) {
        case 404:
          throw new NoSuchViewException("%s", error.message());
        case 409:
          throw new CommitFailedException("Commit failed: %s", error.message());
        case 500:
        case 502:
        case 503:
        case 504:
          throw new CommitStateUnknownException(
              new ServiceFailureException("Service failed: %s: %s", error.code(), error.message()));
      }

      super.accept(error);
    }
  }

  /** View level error handler. */
  private static class ViewErrorHandler extends DefaultErrorHandler {
    private static final ErrorHandler INSTANCE = new ViewErrorHandler();

    @Override
    public void accept(ErrorResponse error) {
      switch (error.code()) {
        case 404:
          if (NoSuchNamespaceException.class.getSimpleName().equals(error.type())) {
            throw new NoSuchNamespaceException("%s", error.message());
          } else {

View on GitHub (pinned to 86d9c8fc54)