{"record":{"id":"de2661cb1d47dfa8","repo":"apache/iceberg","slug":"remote-scan-planning-for-planid-s-did-not-comple","errorCode":null,"errorMessage":"Remote scan planning for planId: %s did not complete within configured limits (timeout=%d ms, maxRetries=%d)","messagePattern":"Remote scan planning for planId: (.+?) did not complete within configured limits \\(timeout=(.+?) ms, maxRetries=(.+?)\\)","errorType":"exception","errorClass":"RemotePlanTimeoutException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java","lineNumber":306,"sourceCode":"                  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\"\n                  + \" (timeout=%d ms, maxRetries=%d)\",\n              planId,\n              maxWaitTimeMs,\n              MAX_RETRIES),\n          e);\n    }\n\n    FetchPlanningResultResponse response = result.get();\n\n    this.scanFileIO =\n        !response.credentials().isEmpty() ? scanFileIO(response.credentials()) : table().io();\n\n    return scanTasksIterable(response.planTasks(), response.fileScanTasks());\n  }\n","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java#L288-L324","documentation":"Thrown as RemotePlanTimeoutException when the submitted remote scan plan never reached a terminal COMPLETED/FAILED/CANCELLED state within the configured polling limits (timeout and max retries). The client stops polling and reports the planId for follow-up.","triggerScenarios":"fetchPlanningResult exhausts its Tasks retry loop (maxRetries attempts each waiting up to timeout bounds) while the server keeps returning planStatus SUBMITTED.","commonSituations":"Very large scans where server planning exceeds client wait time; slow/overloaded REST planning service; client timeout properties set too low (e.g. rest.scan.plan.timeout-ms, max-retries).","solutions":["Increase client wait properties (scan planning timeout ms and max retries) so polling covers server planning duration","Reduce scan scope (partition filters) so server planning finishes faster","Scale/optimize the server's planning service","Use the reported planId to check server state; fetch the plan result out-of-band if the API allows"],"exampleFix":"// before\ncatalog.properties: rest.client.timeout=30000\n// after\nconf.put(\"rest.scan.plan.timeout-ms\", \"300000\");\nconf.put(\"rest.scan.plan.max-retries\", \"20\");","handlingStrategy":"retry","validationCode":"// ensure client wait budget exceeds expected planning time\nlong timeoutMs = Long.parseLong(conf.getOrDefault(\"rest.scan.plan.timeout-ms\", \"30000\"));\nint maxRetries = Integer.parseInt(conf.getOrDefault(\"rest.scan.plan.max-retries\", \"10\"));","typeGuard":null,"tryCatchPattern":"try { scan.planFiles(); } catch (RemotePlanTimeoutException e) {\n  // e carries planId; optionally re-fetch or re-plan with bigger budget\n}","preventionTips":["Size timeout/max-retries to cover worst-case server planning duration","Prune scans with partition/filter predicates to shorten server planning","Alert on slow planning service latency"],"tags":["rest-catalog","timeout","async","scan-planning"],"backgroundTag":"request-timeout","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"}