{"record":{"id":"ebbb8884a7024909","repo":"apache/iceberg","slug":"failuremessage-id-response-errorresponse","errorCode":null,"errorMessage":"failureMessage(id, response.errorResponse())","messagePattern":"failureMessage\\(id, response\\.errorResponse\\(\\)\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java","lineNumber":291,"sourceCode":"          .run(\n              id -> {\n                FetchPlanningResultResponse response =\n                    client.get(\n                        resourcePaths.plan(tableIdentifier, id),\n                        headers,\n                        FetchPlanningResultResponse.class,\n                        headers,\n                        ErrorHandlers.planErrorHandler(),\n                        parserContext);\n\n                switch (response.planStatus()) {\n                  case COMPLETED:\n                    result.set(response);\n                    break;\n                  case SUBMITTED:\n                    throw new NotCompleteException();\n                  case FAILED:\n                    throw new IllegalStateException(failureMessage(id, response.errorResponse()));\n                  case CANCELLED:\n                    throw new IllegalStateException(\n                        String.format(\n                            Locale.ROOT, \"Remote scan planning cancelled for planId: %s\", id));\n                  default:\n                    throw new IllegalStateException(\n                        String.format(\n                            Locale.ROOT,\n                            \"Invalid planStatus: %s for planId: %s\",\n                            response.planStatus(),\n                            id));\n                }\n              });\n    } catch (NotCompleteException e) {\n      throw new RemotePlanTimeoutException(\n          String.format(\n              Locale.ROOT,\n              \"Remote scan planning for planId: %s did not complete within configured limits\"","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java#L273-L309","documentation":"Thrown while polling for a submitted remote scan plan (fetchPlanningResult) when the server reports planStatus=FAILED. The server-side planning job completed with an error; the server's errorResponse is included via failureMessage.","triggerScenarios":"A scan was SUBMITTED and the polling loop (Tasks retry) then fetched a result with planStatus FAILED; IllegalStateException propagates out of planTableScan/planFiles.","commonSituations":"Long-running or large scans whose server-side planning job fails midway; server errors like failed manifest reads, expired snapshot, or resource exhaustion during async planning.","solutions":["Inspect the server errorResponse text in the exception for the root cause","Check REST server logs for the planId","Retry the scan or reduce its scope (prune partitions/filters)","Disable remote planning to plan client-side if the server is unreliable"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { scan.planFiles(); } catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"Remote scan planning failed\")) {\n    // retry with client-side planning\n  } else throw e;\n}","preventionTips":["Keep scans scoped with filters to reduce server-side planning failures","Ensure the planning service can read the table's metadata and data files","Monitor server logs and alert on failed planIds"],"tags":["rest-catalog","async","scan-planning","polling"],"backgroundTag":"api-error-response","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"}