{"record":{"id":"18f75d9b3bf96c9d","repo":"apache/iceberg","slug":"unknown-planning-mode-mode","errorCode":null,"errorMessage":"Unknown planning mode: ${mode}","messagePattern":"Unknown planning mode: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/BaseDistributedDataScan.java","lineNumber":256,"sourceCode":"  private boolean shouldPlanLocally(PlanningMode mode, List<ManifestFile> manifests) {\n    if (context().planWithCustomizedExecutor()) {\n      return true;\n    }\n\n    switch (mode) {\n      case LOCAL:\n        return true;\n\n      case DISTRIBUTED:\n        return manifests.isEmpty();\n\n      case AUTO:\n        return remoteParallelism() <= localParallelism\n            || manifests.size() <= 2 * localParallelism\n            || totalSize(manifests) <= localPlanningSizeThreshold;\n\n      default:\n        throw new IllegalArgumentException(\"Unknown planning mode: \" + mode);\n    }\n  }\n\n  private long totalSize(List<ManifestFile> manifests) {\n    return manifests.stream().mapToLong(ManifestFile::length).sum();\n  }\n\n  private boolean shouldCopyDataFiles(boolean planDataLocally, boolean loadColumnStats) {\n    return planDataLocally\n        || shouldCopyRemotelyPlannedDataFiles()\n        || (loadColumnStats && !shouldReturnColumnStats());\n  }\n\n  @SuppressWarnings(\"unchecked\")\n  private CloseableIterable<ScanTask> planFileTasksLocally(\n      List<ManifestFile> dataManifests, List<ManifestFile> deleteManifests) {\n    LOG.info(\"Planning file tasks locally for table {}\", table().name());\n    ManifestGroup manifestGroup = newManifestGroup(dataManifests, deleteManifests);","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseDistributedDataScan.java#L238-L274","documentation":"shouldPlanLocally() switches on a configured planning mode (enum of AUTO and remote/local preferences); an unrecognized mode reaches the default branch and throws IllegalArgumentException('Unknown planning mode'). This indicates the stored mode value is not a valid PlanningMode, typically from an invalid property value or a version mismatch where an older core sees a newer mode name.","triggerScenarios":"Setting the distributed-scan planning mode property to a value outside the enum, or deserializing a mode saved by a newer Iceberg version.","commonSituations":"Typo in configuration property value (e.g. 'autto', 'remote-paralell'); config from a different Iceberg version; programmatic construction with a null/foreign mode object.","solutions":["Set the planning mode property to one of the valid enum values (auto, and the defined remote/local modes)","Check for Iceberg version mismatch between the writer of the config and the reader","Use the enum constant programmatically instead of a raw string where possible","Validate configuration values at startup before launching scans"],"exampleFix":"// before\nString mode = conf.get(\"iceberg.distributed.plan-mode\"); // e.g. \"automatic\"\n// after\nString mode = conf.get(\"iceberg.distributed.plan-mode\", \"auto\"); // must be a valid PlanningMode name\nPreconditions.checkArgument(mode.equals(\"auto\") || mode.equals(\"local\") || mode.equals(\"remote\"),\n    \"Invalid planning mode: %s\", mode);","handlingStrategy":"validation","validationCode":"String mode = props.get(\"plan-mode\");\nSet<String> valid = Set.of(\"auto\", \"local\", \"remote\"); // adjust to actual enum names\nif (mode != null && !valid.contains(mode)) {\n  throw new IllegalArgumentException(\"Invalid planning mode: \" + mode);\n}","typeGuard":"null","tryCatchPattern":"try { planFiles(); } catch (IllegalArgumentException e) { /* fix plan-mode config */ }","preventionTips":["Copy valid enum values from the Iceberg PlanningMode enum, don't free-type them","Align Iceberg versions across config producers and consumers","Validate all scan-related properties at app startup","Use programmatic enum constants where available"],"tags":["configuration","enum","planning"],"backgroundTag":"invalid-enum-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}