{"record":{"id":"7fc6f68553cd00da","repo":"apache/iceberg","slug":"failed-to-plan-files","errorCode":null,"errorMessage":"Failed to plan files","messagePattern":"Failed to plan files","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/BaseDistributedDataScan.java","lineNumber":183,"sourceCode":"        newDeletesFuture(deleteManifests, planDeletesLocally, monitorPool);\n\n    CompletableFuture<Iterable<CloseableIterable<DataFile>>> dataFuture =\n        newDataFuture(dataManifests, planDataLocally, loadColumnStats, monitorPool);\n\n    try {\n      Iterable<CloseableIterable<ScanTask>> fileTasks =\n          toFileTasks(dataFuture, deletesFuture, copyDataFiles);\n\n      if (shouldPlanWithExecutor() && (planDataLocally || mayHaveEqualityDeletes)) {\n        return new ParallelIterable<>(fileTasks, planExecutor());\n      } else {\n        return CloseableIterable.concat(fileTasks);\n      }\n\n    } catch (CompletionException e) {\n      deletesFuture.cancel(true /* may interrupt */);\n      dataFuture.cancel(true /* may interrupt */);\n      throw new RuntimeException(\"Failed to plan files\", e);\n\n    } finally {\n      monitorPool.shutdown();\n    }\n  }\n\n  @Override\n  public CloseableIterable<ScanTaskGroup<ScanTask>> planTasks() {\n    return TableScanUtil.planTaskGroups(\n        planFiles(), targetSplitSize(), splitLookback(), splitOpenFileCost());\n  }\n\n  private List<ManifestFile> findMatchingDataManifests(Snapshot snapshot) {\n    List<ManifestFile> dataManifests = snapshot.dataManifests(table().io());\n    scanMetrics().totalDataManifests().increment(dataManifests.size());\n\n    List<ManifestFile> matchingDataManifests = filterManifests(dataManifests);\n    int skippedDataManifestsCount = dataManifests.size() - matchingDataManifests.size();","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseDistributedDataScan.java#L165-L201","documentation":"BaseDistributedDataScan.doPlanFiles() throws RuntimeException('Failed to plan files') when a CompletionException escapes the coordinated planning of data and delete futures (e.g. a remote scan task failed or was cancelled). The two futures are cancelled and the underlying exception is attached as the cause. It wraps whatever failure occurred during distributed scan planning.","triggerScenarios":"The dataFiles or deletes CompletableFuture completes exceptionally (task executor failure, remote manifest read error, cancellation) while joining results in doPlanFiles.","commonSituations":"Executor thread death or OOM in a distributed planner; timeouts reading manifests remotely; shutdown of the monitoring pool mid-plan.","solutions":["Inspect e.getCause() (the CompletionException cause) for the root failure","Retry the scan planning; transient executor/storage failures may recover","Increase executor thread pool size or timeout budgets for remote planning","Fall back to local planning by tuning planning-mode properties (see shouldPlanLocally)","Check task executor logs in the distributed environment for the original stack"],"exampleFix":"// before\nCloseableIterable<FileScanTask> tasks = distributedScan.planFiles(); // RuntimeException on remote failure\n// after\ntry {\n  tasks = distributedScan.planFiles();\n} catch (RuntimeException e) {\n  Throwable root = e.getCause() == null ? e : e.getCause();\n  LOG.error(\"Planning failed: {}\", root.getMessage(), root);\n  tasks = table.newScan().planFiles(); // fall back to local planning\n}","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"null","tryCatchPattern":"try { tasks = scan.planFiles(); } catch (RuntimeException e) { Throwable cause = e.getCause(); /* CompletionException cause has the root failure */ }","preventionTips":["Monitor remote planning executor health and timeouts","Log and inspect getCause() for root-cause triage","Tune planning mode so remote planning is used only when beneficial","Add retry with backoff around scan planning"],"tags":["planning","concurrency","distributed"],"backgroundTag":"http-request-failed","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"}