{"record":{"id":"e11af7030521f866","repo":"apache/iceberg","slug":"planning-failed-for-plan-id","errorCode":null,"errorMessage":"Planning failed for plan ID: {}","messagePattern":"Planning failed for plan ID: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java","lineNumber":269,"sourceCode":"        PropertyUtil.propertyAsLong(\n            catalogProperties,\n            RESTCatalogProperties.REST_SCAN_PLANNING_POLL_TIMEOUT_MS,\n            RESTCatalogProperties.REST_SCAN_PLANNING_POLL_TIMEOUT_MS_DEFAULT);\n    Preconditions.checkArgument(\n        maxWaitTimeMs > 0,\n        \"Invalid value for %s: %s (must be positive)\",\n        RESTCatalogProperties.REST_SCAN_PLANNING_POLL_TIMEOUT_MS,\n        maxWaitTimeMs);\n\n    AtomicReference<FetchPlanningResultResponse> result = new AtomicReference<>();\n    try {\n      Tasks.foreach(planId)\n          .exponentialBackoff(MIN_SLEEP_MS, MAX_SLEEP_MS, maxWaitTimeMs, SCALE_FACTOR)\n          .retry(MAX_RETRIES)\n          .onlyRetryOn(NotCompleteException.class)\n          .onFailure(\n              (id, err) -> {\n                LOG.warn(\"Planning failed for plan ID: {}\", id, err);\n                cleanupPlanResources();\n              })\n          .throwFailureWhenFinished()\n          .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;","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/rest/RESTTableScan.java#L251-L287","documentation":"RESTTableScan polls the REST catalog for an asynchronous server-side plan result; each poll that sees an incomplete plan throws NotCompleteException and Tasks retries with exponential backoff. When retries are exhausted (plan not completed within max wait) this warning is logged, plan resources are cleaned up, and the failure is rethrown.","triggerScenarios":"Executing a scan against a catalog using server-side planning (planning-enabled) where the plan does not complete within rest.plan.max-wait-ms and MAX_RETRIES polls.","commonSituations":"Overloaded REST catalog or slow underlying object store, network latency between client and server, too-small rest.plan.max-wait-ms for large tables, server having evicted/dropped the plan resources.","solutions":["Increase table property 'rest.plan.max-wait-ms' (and check MIN/MAX polling intervals) to allow more time.","Investigate REST catalog server load/health and its planning backend latency.","Retry the query after cleanup; the plan resources were released.","Disable server-side planning if the catalog does not reliably support it (use default client-side planning)."],"exampleFix":"// before\nALTER TABLE t SET TBLPROPERTIES ('rest.plan.max-wait-ms'='5000');\n// after\nALTER TABLE t SET TBLPROPERTIES ('rest.plan.max-wait-ms'='60000');","handlingStrategy":"retry","validationCode":"long waitMs = Long.parseLong(table.properties().getOrDefault(\"rest.plan.max-wait-ms\", \"30000\"));\nif (tableSizeEstimateLarge && waitMs < 60000) { /* raise wait or avoid server-side planning */ }","typeGuard":null,"tryCatchPattern":"try { closeableIterable = scan.planFiles(); } catch (NotCompleteException | RESTException e) { LOG.warn(\"plan did not finish in time; retrying\", e); scan.planFiles(); }","preventionTips":["Raise rest.plan.max-wait-ms for large tables","Monitor catalog server planning latency","Fall back to client-side planning if server planning is unreliable"],"tags":["rest","scan-planning","timeout","retry"],"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"}