{"record":{"id":"708f0b4cd9f9d0b5","repo":"apache/iceberg","slug":"unexpected-command-command-708f0b","errorCode":null,"errorMessage":"Unexpected command: ${command}","messagePattern":"Unexpected command: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkWriteConf.java","lineNumber":379,"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":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkWriteConf.java#L361-L397","documentation":"SparkWriteConf.copyOnWriteDistributionMode maps a Spark write Command (DELETE, UPDATE, MERGE, OVERWRITE/INSERT) to a distribution mode and throws IllegalArgumentException('Unexpected command: ' + command) for any Command outside the switch's cases. The write configuration only supports distribution-mode resolution for the recognized DML commands; anything else is a caller bug.","triggerScenarios":"Querying copyOnWriteDistributionMode(command) with a Command other than DELETE/UPDATE/MERGE (e.g. a plain INSERT/OVERWRITE command instance passed in error, or an unexpected enum constant), typically from internal write-planning code.","commonSituations":"Library-internal misuse or version mismatch where a new Command constant was added but the switch wasn't updated; custom extensions calling SparkWriteConf directly with the wrong command.","solutions":["Pass the correct Command enum constant (DELETE, UPDATE, or MERGE) for a copy-on-write distribution lookup","For plain append/overwrite writes, use the appropriate SparkWriteConf methods (e.g. distributionMode()) rather than the CoW-specific one","Upgrade Iceberg if a newly introduced Command constant is not handled","Add a case for the new command if you maintain a fork of SparkWriteConf"],"exampleFix":"// before\nDistributionMode mode = writeConf.copyOnWriteDistributionMode(Command.INSERT); // throws\n// after\nDistributionMode mode = writeConf.distributionMode(); // correct entry point for appends","handlingStrategy":"validation","validationCode":"if (command != Command.DELETE && command != Command.UPDATE && command != Command.MERGE) {\n  throw new IllegalArgumentException(\"copyOnWriteDistributionMode requires DELETE/UPDATE/MERGE, got \" + command);\n}","typeGuard":"boolean isCoWCommand(Command c) { return c == Command.DELETE || c == Command.UPDATE || c == Command.MERGE; }","tryCatchPattern":"try {\n  mode = writeConf.copyOnWriteDistributionMode(command);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Unexpected command\")) { mode = writeConf.distributionMode(); }\n  else throw e;\n}","preventionTips":["Call copyOnWriteDistributionMode only for row-level DML commands","Use writeConf.distributionMode() for append/overwrite writes","Update switches whenever the Command enum gains new constants"],"tags":["invalid-argument-value","spark","write-config"],"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"}