{"record":{"id":"373d97eda50c5a6e","repo":"apache/beam","slug":"cannot-encode-a-null-byte-bytecoder","errorCode":null,"errorMessage":"cannot encode a null Byte","messagePattern":"cannot encode a null Byte","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/ByteCoder.java","lineNumber":44,"sourceCode":"\n/** A {@link ByteCoder} encodes {@link Byte} values in 1 byte using Java serialization. */\npublic class ByteCoder extends AtomicCoder<Byte> {\n\n  public static ByteCoder of() {\n    return INSTANCE;\n  }\n\n  /////////////////////////////////////////////////////////////////////////////\n\n  private static final ByteCoder INSTANCE = new ByteCoder();\n  private static final TypeDescriptor<Byte> TYPE_DESCRIPTOR = new TypeDescriptor<Byte>() {};\n\n  private ByteCoder() {}\n\n  @Override\n  public void encode(Byte value, OutputStream outStream) throws IOException, CoderException {\n    if (value == null) {\n      throw new CoderException(\"cannot encode a null Byte\");\n    }\n    outStream.write(value);\n  }\n\n  @Override\n  public Byte decode(InputStream inStream) throws IOException, CoderException {\n    try {\n      // value will be between 0-255, -1 for EOF\n      int value = inStream.read();\n      if (value == -1) {\n        throw new EOFException(\"EOF encountered decoding 1 byte from input stream\");\n      }\n      return (byte) value;\n    } catch (EOFException | UTFDataFormatException exn) {\n      // These exceptions correspond to decoding problems, so change\n      // what kind of exception they're branded as.\n      throw new CoderException(exn);\n    }","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/ByteCoder.java#L26-L62","documentation":"ByteCoder.encode throws CoderException when the Byte value to encode is null. Beam coders for boxed types reject nulls unless wrapped in NullableCoder, because the wire format has no representation for null.","triggerScenarios":"Calling ByteCoder.of().encode(null, outStream), or a DoFn emitting null Byte values into a PCollection<Byte> coded with plain ByteCoder, or a sink serializing null Byte elements.","commonSituations":"Nullable map values, JSON/database rows with missing numeric columns mapped to null Byte, aggregation results that default to null, a schema change making a previously non-null column nullable.","solutions":["Filter or default null values before they reach the coder: value == null ? (byte) 0 : value","Use NullableCoder.of(ByteCoder.of()) as the PCollection's coder when nulls are valid","Fix the upstream transform to skip null records","Model nullable data with a sentinel or Optional-like type instead of a bare Byte"],"exampleFix":"// before\nout.output(row.getOptionalByte()); // may be null\n// after\nByte b = row.getOptionalByte();\nout.output(b == null ? (byte) 0 : b);\n// or: .setCoder(NullableCoder.of(ByteCoder.of()))","handlingStrategy":"validation","validationCode":"if (value == null) throw new IllegalArgumentException(\"null Byte not supported by ByteCoder; filter or use NullableCoder\");","typeGuard":"static boolean isNonNullByte(Byte b) { return b != null; }","tryCatchPattern":"try { coder.encode(value, out); } catch (CoderException e) { /* null Byte: default or dead-letter */ }","preventionTips":["Default null numerics at source-read time (coalesce to 0 or a sentinel)","Enable NullableCoder for nullable fields and test encode/decode round-trips"],"tags":["java","beam","coders","null"],"backgroundTag":"null-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}