apache/iceberg · error · RESTException

Unable to process (code: , type: )

Error message

Unable to process (code: %s, type: %s): %s

What it means

RESTNamespaceErrorHandler.accept(RESTError) maps known REST namespace error codes (400, 404, 409, 422) to typed Iceberg exceptions. For any other HTTP status returned with a REST error payload, it falls through to the base handler, which throws a generic RESTException formatted as 'Unable to process (code: <status>, type: <error type>): <message>'.

Solutions

1. Inspect the code and type fields in the message to identify the server-side failure
2. Check server logs for the corresponding request failure
3. Add handling/retry for the specific status (e.g. retry on 502/503, fix credentials on 401)
4. Upgrade/patch the server to return a spec-defined error code for the condition

Example fix

// before
try { catalog.createNamespace(ns); } catch (RESTException e) { /* Unable to process (code: 500 ...) */ }
// after
try {
  catalog.createNamespace(ns);
} catch (RESTException e) {
  if (e.getMessage().contains("code: 503")) { retry(); } else { throw e; }
}

try { catalog.loadNamespace(ns); } catch (RESTException e) { /* inspect code/type in message; retry transient 5xx */ }

When it happens

Trigger: A namespace-scoped REST call (create/load/list/delete namespace) where the server replies with an error code outside the mapped set (e.g. 401, 403, 500, 503) and an ErrorResponse body.

Common situations: REST catalog server returning 500 on a transient backend failure; auth proxy responding 401; load balancer returning 502/503 for namespace operations.

Related errors

• Invalid namespace
• Invalid namespace update, cannot simultaneously set and…
• Invalid table identifier
• Unable to parse error response
• Unknown error handler

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

Appendix: source

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

  /** Request error handler specifically for create-read-update ops on namespaces. */
  private static class NamespaceErrorHandler extends DefaultErrorHandler {
    private static final ErrorHandler INSTANCE = new NamespaceErrorHandler();

    @Override
    public void accept(ErrorResponse error) {
      switch (error.code()) {
        case 400:
          if (NamespaceNotEmptyException.class.getSimpleName().equals(error.type())) {
            throw new NamespaceNotEmptyException("%s", error.message());
          }
          throw new BadRequestException("Malformed request: %s", error.message());
        case 404:
          throw new NoSuchNamespaceException("%s", error.message());
        case 409:
          throw new AlreadyExistsException("%s", error.message());
        case 422:
          throw createRESTException(error);
      }

      super.accept(error);
    }
  }

  /** Request error handler for drop namespace operations. */
  private static class DropNamespaceErrorHandler extends NamespaceErrorHandler {
    private static final ErrorHandler INSTANCE = new DropNamespaceErrorHandler();

    @Override
    public void accept(ErrorResponse error) {
      if (error.code() == 409) {
        throw new NamespaceNotEmptyException("%s", error.message());
      }

      super.accept(error);
    }

View on GitHub (pinned to 86d9c8fc54)