{"record":{"id":"d46e22d3f8d3d3ca","repo":"apache/iceberg","slug":"failuremessage-planid-response-errorresponse","errorCode":null,"errorMessage":"failureMessage(planId, response.errorResponse())","messagePattern":"failureMessage\\(planId, response\\.errorResponse\\(\\)\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java","lineNumber":222,"sourceCode":"            PlanTableScanResponse.class,\n            headers,\n            ErrorHandlers.tableErrorHandler(),\n            stringStringMap -> {},\n            parserContext);\n\n    this.planId = response.planId();\n    PlanStatus planStatus = response.planStatus();\n    this.scanFileIO =\n        !response.credentials().isEmpty() ? scanFileIO(response.credentials()) : table().io();\n\n    switch (planStatus) {\n      case COMPLETED:\n        return scanTasksIterable(response.planTasks(), response.fileScanTasks());\n      case SUBMITTED:\n        Endpoint.check(supportedEndpoints, Endpoint.V1_FETCH_TABLE_SCAN_PLAN);\n        return fetchPlanningResult();\n      case FAILED:\n        throw new IllegalStateException(failureMessage(planId, response.errorResponse()));\n      default:\n        throw new IllegalStateException(\n            String.format(\"Invalid planStatus: %s for planId: %s\", planStatus, planId));\n    }\n  }\n\n  private FileIO scanFileIO(List<Credential> storageCredentials) {\n    ImmutableMap.Builder<String, String> builder =\n        ImmutableMap.<String, String>builder().putAll(catalogProperties);\n    if (null != planId) {\n      builder.put(RESTCatalogProperties.REST_SCAN_PLAN_ID, planId);\n    }\n\n    Map<String, String> properties = builder.buildKeepingLast();\n    FileIO ioForScan =\n        CatalogUtil.loadFileIO(\n            catalogProperties.getOrDefault(CatalogProperties.FILE_IO_IMPL, DEFAULT_FILE_IO_IMPL),\n            properties,","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java#L204-L240","documentation":"Thrown by RESTTableScan when a remotely planned scan reports planStatus=FAILED. The server-side scan planning job failed and the errorResponse details from the REST server are embedded in the message via failureMessage. The scan cannot produce tasks without a completed plan.","triggerScenarios":"Calling planFiles/planTableScan against a REST catalog that supports async scan planning (Endpoint.V1_FETCH_TABLE_SCAN_PLAN); the server returns a FetchScanPlanningResult with planStatus FAILED and a non-null errorResponse.","commonSituations":"Server-side planning failures: invalid snapshot references, table metadata unreadable by the planning service, server OOM or internal errors during large partitioned scans, incompatible scan filters the server cannot evaluate.","solutions":["Read the embedded server errorResponse message in the exception for the root cause and fix the server-side condition","Retry the scan; if persistent, fall back to a catalog that plans scans client-side","Verify the table metadata/snapshot is valid and accessible to the REST planning service","Check REST server logs for the failing planId"],"exampleFix":"try {\n  TableScan scan = table.newScan().planWithRemotePlanning(true);\n  scan.planFiles();\n} catch (IllegalStateException e) {\n  // e.getMessage() contains the server errorResponse; fall back\n  scan = table.newScan().planWithRemotePlanning(false);\n  scan.planFiles();\n}","handlingStrategy":"try-catch","validationCode":"// pre-check supported endpoints before enabling remote planning\nboolean remotePlanning =\n  supportedEndpoints.contains(Endpoint.V1_FETCH_TABLE_SCAN_PLAN);","typeGuard":null,"tryCatchPattern":"try { scan.planFiles(); } catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"Remote scan planning failed\")) { /* fallback to client planning */ }\n  else throw e;\n}","preventionTips":["Verify the REST server advertises the fetch-scan-plan endpoint before enabling async planning","Keep client and server Iceberg REST spec versions aligned","Monitor server-side planning health for large scans"],"tags":["rest-catalog","scan-planning","async","server-error"],"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"}