{"record":{"id":"456939cfbcdff34f","repo":"apache/iceberg","slug":"unsupported-streaming-write-mode","errorCode":null,"errorMessage":"Unsupported streaming write mode: ","messagePattern":"Unsupported streaming write mode: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkWriteBuilder.java","lineNumber":170,"sourceCode":"          return asDynamicOverwrite();\n        } else if (mode instanceof CopyOnWriteOperation cow) {\n          return asCopyOnWriteOperation(cow.scan(), cow.isolationLevel());\n        } else {\n          return asBatchAppend();\n        }\n      }\n\n      @Override\n      public StreamingWrite toStreaming() {\n        if (mode instanceof OverwriteByFilter overwrite) {\n          Preconditions.checkState(\n              overwrite.expr() == Expressions.alwaysTrue(),\n              \"Unsupported streaming overwrite filter: \" + overwrite.expr());\n          return asStreamingOverwrite();\n        } else if (mode == null || mode instanceof Append) {\n          return asStreamingAppend();\n        } else {\n          throw new IllegalStateException(\"Unsupported streaming write mode: \" + mode);\n        }\n      }\n    };\n  }\n\n  private SparkWriteRequirements writeRequirements() {\n    if (mode instanceof CopyOnWriteOperation cow) {\n      return writeConf.copyOnWriteRequirements(cow.command());\n    } else {\n      return writeConf.writeRequirements();\n    }\n  }\n\n  private void validateRowLineage() {\n    Preconditions.checkArgument(\n        writeIncludesRowLineage() || !writeNeedsRowLineage(),\n        \"Row lineage information is missing for write in mode: %s\",\n        mode);","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkWriteBuilder.java#L152-L188","documentation":"SparkWriteBuilder.toStreaming throws this IllegalStateException when a streaming query requests a write mode that Iceberg's Spark streaming sink does not support. Only Append (or a null mode treated as append) and the Complete/Update overwrite paths are handled.","triggerScenarios":"Invoking toStreaming with a mode such as StreamingDelete or any other SaveMode/WriteMode instance that is not Append and not handled by the branch above the throw.","commonSituations":"Using Iceberg as a streaming sink with an unsupported write mode (e.g. truncate or delete semantics in micro-batch), or framework upgrades passing new mode types the connector does not yet support.","solutions":["Use Append mode for streaming writes, or a valid overwrite mode handled by asStreamingOverwrite","Restructure the job to avoid streaming delete/truncate modes (e.g. batch job for deletes)","Upgrade Iceberg if a newer version supports the desired streaming mode"],"exampleFix":"// before\nwriteToSink(sinkMode = STREAMING_DELETE);\n// after\nwriteToSink(sinkMode = STREAMING_APPEND);","handlingStrategy":"validation","validationCode":"// Java\nif (!(mode instanceof Append) && !(mode instanceof Overwrite) && mode != null) {\n  throw new UnsupportedOperationException(\"Streaming write mode not supported: \" + mode);\n}","typeGuard":"boolean isStreamingAppendMode(Object mode) {\n  return mode == null || mode instanceof Append;\n}","tryCatchPattern":"try {\n  sparkWrite = writeBuilder.toStreaming();\n} catch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Unsupported streaming write mode\")) {\n    // fall back to batch write or reconfigure to append\n  }\n  throw e;\n}","preventionTips":["Use append (or supported overwrite) modes for streaming sinks","Do deletes/truncates in batch jobs, not streaming","Check supported modes for your Iceberg version before configuring the stream"],"tags":["spark","streaming","unsupported-mode"],"backgroundTag":"unsupported-operation","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"}