apache/iceberg · error · RESTException

Error occurred while processing

Error message

Error occurred while processing %s request

What it means

HTTPClient.execute wraps any IOException thrown while sending the request or receiving the response in a RESTException with this message. It means the HTTP exchange itself failed at the transport level (connection problems, broken streams, socket errors), not that the server returned an error status — error statuses go through the configured errorHandler instead. The causing IOException is chained as the cause.

Solutions

1. Inspect the chained cause (e.getCause()) to find the underlying IOException and fix its root cause (connectivity, TLS, proxy).
2. Retry the request — transient connection drops are often fixed by enabling client-side retry.
3. Verify the REST catalog URI, network/DNS, and that the server is reachable (curl the endpoint).
4. Check server and proxy timeouts; increase or align them with the client's socket timeout settings.
5. Check server logs for crashes or connection limits around the time of the failure.

Example fix

// before: one-shot call that surfaces transport errors
Table table = catalog.loadTable(identifier);
// after: catch and retry transient transport failures
try {
  Table table = catalog.loadTable(identifier);
} catch (RESTException e) {
  if (e.getCause() instanceof IOException) {
    // retry with backoff or surface a connection-level failure
  }
  throw e;
}

try {
  catalog.loadTable(id);
} catch (RESTException e) {
  if (e.getCause() instanceof IOException && isTransient(e.getCause())) {
    retryWithBackoff(() -> catalog.loadTable(id));
  } else {
    throw e;
  }
}

When it happens

Trigger: Any REST catalog call (loadTable, commit, etc.) where the underlying Apache HttpClient throws IOException during request execution: connection reset, socket timeout surfaced as IOException, premature EOF, or broken connection pool streams.

Common situations: Server closed the connection mid-response; network interruption or proxy dropped the connection; TLS handshake failures surfaced as IOException; Kubernetes ingress terminating long-running requests; keep-alive connections closed by the server between calls.

Related errors

• Failed to convert HTTP response body to string
• Attempted to release already closed HTTP client: key=
• Cannot acquire closed HTTP client
• Cannot assume role to sign REST requests because is not…
• Cannot build StorageCredential, some of required attributes…

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/HTTPClient.java:328

    HttpUriRequestBase request = new HttpUriRequestBase(req.method().name(), req.requestUri());

    req.headers().entries().forEach(e -> request.addHeader(e.name(), e.value()));

    String encodedBody = req.encodedBody();
    if (encodedBody != null) {
      request.setEntity(new StringEntity(encodedBody));
    }

    HttpContext context = HttpClientContext.create();
    try {
      return httpClient.execute(
          request,
          context,
          response ->
              handleResponse(
                  req, response, responseType, errorHandler, responseHeaders, parserContext));
    } catch (IOException e) {
      throw new RESTException(e, "Error occurred while processing %s request", req.method());
    }
  }

  private <T extends RESTResponse> T handleResponse(
      HTTPRequest request,
      ClassicHttpResponse response,
      Class<T> responseType,
      Consumer<ErrorResponse> errorHandler,
      Consumer<Map<String, String>> responseHeaders,
      ParserContext parserContext)
      throws IOException {
    Map<String, String> respHeaders = Maps.newHashMap();
    for (Header header : response.getHeaders()) {
      respHeaders.put(header.getName(), header.getValue());
    }

    responseHeaders.accept(respHeaders);

View on GitHub (pinned to 86d9c8fc54)