{"record":{"id":"4aacfca8338ace65","repo":"apache/iceberg","slug":"server-error-s-s","errorCode":null,"errorMessage":"Server error: %s: %s","messagePattern":"Server error: (.+?): (.+?)","errorType":"exception","errorClass":"ServiceFailureException","httpStatus":500,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/rest/ErrorHandlers.java","lineNumber":350,"sourceCode":"    }\n\n    @Override\n    public void accept(ErrorResponse error) {\n      switch (error.code()) {\n        case 400:\n          if (IllegalArgumentException.class.getSimpleName().equals(error.type())) {\n            throw new IllegalArgumentException(error.message());\n          }\n          throw new BadRequestException(\"Malformed request: %s\", error.message());\n        case 401:\n          throw new NotAuthorizedException(\"Not authorized: %s\", error.message());\n        case 403:\n          throw new ForbiddenException(\"Forbidden: %s\", error.message());\n        case 405:\n        case 406:\n          break;\n        case 500:\n          throw new ServiceFailureException(\"Server error: %s: %s\", error.type(), error.message());\n        case 501:\n          throw new UnsupportedOperationException(error.message());\n        case 503:\n          throw new ServiceUnavailableException(\"Service unavailable: %s\", error.message());\n      }\n\n      throw createRESTException(error);\n    }\n  }\n\n  private static class OAuthErrorHandler extends ErrorHandler {\n    private static final ErrorHandler INSTANCE = new OAuthErrorHandler();\n\n    @Override\n    public ErrorResponse parseResponse(int code, String json) {\n      try {\n        return OAuthErrorResponseParser.fromJson(code, json);\n      } catch (Exception x) {","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/rest/ErrorHandlers.java#L332-L368","documentation":"RESTClient's default error handler maps HTTP 500 responses to ServiceFailureException. The catalog server encountered an unexpected internal error while processing the request; the message includes the server-provided error type and message to aid server-side debugging.","triggerScenarios":"HTTP 500 returned by the REST server during any catalog request — server bug, backend store failure (e.g. underlying metadata DB or object store error), or unhandled exception server-side.","commonSituations":"Catalog backend outage or misconfiguration, server version bug triggered by a specific request shape, resource exhaustion on the server, or corrupted metadata causing server-side NPEs.","solutions":["Read the server-provided error type and message; they usually pinpoint the server-side failure","Retry the request with backoff — many 500s are transient backend issues","Check server logs and health status of the catalog service","If reproducible, report to the catalog operator with the request details and error type"],"exampleFix":"// before\nTable table = catalog.loadTable(identifier); // throws ServiceFailureException on 500\n// after\nRetry.callerRetry -> use backoff:\ntry {\n  Table table = catalog.loadTable(identifier);\n} catch (ServiceFailureException e) {\n  // retry with exponential backoff, or fail over to a replica catalog\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"Tasks.foreach(() -> catalog.loadTable(identifier))\n    .retry(3)\n    .exponentialBackoff(100, 60000)\n    .throwFailureWhenFinished();","preventionTips":["Build in retry with backoff for catalog calls","Monitor catalog server health before large batch operations","Report reproducible 500s to the catalog operator with error type and message"],"tags":["rest","http-500","server-error","retry"],"backgroundTag":"upstream-api-error","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}