{"record":{"id":"7f0f1ad64c6347bb","repo":"apache/iceberg","slug":"unexpected-command","errorCode":null,"errorMessage":"Unexpected command: ","messagePattern":"Unexpected command: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkWriteConf.java","lineNumber":369,"sourceCode":"    return SparkWriteUtil.copyOnWriteRequirements(\n        table,\n        command,\n        copyOnWriteDistributionMode(command),\n        fanoutWriterEnabled(),\n        dataAdvisoryPartitionSize());\n  }\n\n  @VisibleForTesting\n  DistributionMode copyOnWriteDistributionMode(Command command) {\n    switch (command) {\n      case DELETE:\n        return deleteDistributionMode();\n      case UPDATE:\n        return updateDistributionMode();\n      case MERGE:\n        return copyOnWriteMergeDistributionMode();\n      default:\n        throw new IllegalArgumentException(\"Unexpected command: \" + command);\n    }\n  }\n\n  public SparkWriteRequirements positionDeltaRequirements(Command command) {\n    if (ignoreTableDistributionAndOrdering()) {\n      LOG.info(\"Skipping distribution/ordering: disabled per job configuration\");\n      return SparkWriteRequirements.EMPTY;\n    }\n\n    return SparkWriteUtil.positionDeltaRequirements(\n        table,\n        command,\n        positionDeltaDistributionMode(command),\n        fanoutWriterEnabled(),\n        command == DELETE ? deleteAdvisoryPartitionSize() : dataAdvisoryPartitionSize());\n  }\n\n  @VisibleForTesting","sourceCodeStart":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkWriteConf.java#L351-L387","documentation":"SparkWriteConf.copyOnWriteDistributionMode resolves the distribution mode for a copy-on-write write based on the RowLevelCommand (DELETE, UPDATE, MERGE). If the command is none of these, it throws IllegalArgumentException(\"Unexpected command: \" + command), signaling a programming error rather than user misconfiguration - the command enum was extended or an unexpected value was passed.","triggerScenarios":"Passing a Command value other than DELETE, UPDATE, or MERGE (e.g. Command.INSERT or a newly added enum constant) into copyOnWriteDistributionMode via the write-conf resolution path.","commonSituations":"Upgrading Iceberg where a new RowLevelCommand constant was added but SparkWriteConf branches were not updated (version mismatch between modules); custom code invoking the conf method with an unexpected command.","solutions":["Ensure all Iceberg modules are the same version so Command enums and SparkWriteConf branches match","Only call copyOnWriteDistributionMode for row-level commands (DELETE/UPDATE/MERGE); route other commands elsewhere","If a new Command constant was introduced, update the switch to handle it"],"exampleFix":"// before\nDistributionMode mode = writeConf.copyOnWriteDistributionMode(Command.INSERT); // throws\n// after\nif (command == Command.INSERT) {\n  mode = writeConf.distributionMode(); // append path\n} else {\n  mode = writeConf.copyOnWriteDistributionMode(command);\n}","handlingStrategy":"validation","validationCode":"if (command != Command.DELETE && command != Command.UPDATE && command != Command.MERGE) {\n  throw new IllegalArgumentException(\"CoW distribution mode requires DELETE/UPDATE/MERGE, got: \" + command);\n}","typeGuard":"boolean isRowLevelCommand(Command c) {\n  return c == Command.DELETE || c == Command.UPDATE || c == Command.MERGE;\n}","tryCatchPattern":"try {\n  mode = writeConf.copyOnWriteDistributionMode(command);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Unexpected command {}, defaulting distribution mode\", command, e);\n  mode = writeConf.distributionMode();\n}","preventionTips":["Route append/CTAS writes to the general distributionMode API, not the CoW row-level one","Keep all Iceberg modules on identical versions","Add exhaustive switch handling when Command gains new constants","Unit-test write conf resolution for each Command value"],"tags":["spark","configuration","enum","copy-on-write"],"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"}