{"record":{"id":"4a8f23ca5ff946f6","repo":"apache/beam","slug":"cannot-encode-a-null-byte","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/ByteArrayCoder.java","lineNumber":63,"sourceCode":"  }\n\n  /////////////////////////////////////////////////////////////////////////////\n\n  private static final ByteArrayCoder INSTANCE = new ByteArrayCoder();\n  private static final TypeDescriptor<byte[]> TYPE_DESCRIPTOR = new TypeDescriptor<byte[]>() {};\n\n  private ByteArrayCoder() {}\n\n  @Override\n  public void encode(byte[] value, OutputStream outStream) throws IOException, CoderException {\n    encode(value, outStream, Context.NESTED);\n  }\n\n  @Override\n  public void encode(byte[] value, OutputStream outStream, Context context)\n      throws IOException, CoderException {\n    if (value == null) {\n      throw new CoderException(\"cannot encode a null byte[]\");\n    }\n    if (!context.isWholeStream) {\n      VarInt.encode(value.length, outStream);\n      outStream.write(value);\n    } else {\n      outStream.write(value);\n    }\n  }\n\n  /**\n   * Encodes the provided {@code value} with the identical encoding to {@link #encode}, but with\n   * optimizations that take ownership of the value.\n   *\n   * <p>Once passed to this method, {@code value} should never be observed or mutated again.\n   */\n  public void encodeAndOwn(byte[] value, OutputStream outStream, Context context)\n      throws IOException, CoderException {\n    if (!context.isWholeStream) {","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/ByteArrayCoder.java#L45-L81","documentation":"ByteArrayCoder.encode received a null byte[] and threw CoderException: this coder writes a length-prefixed byte sequence with no null sentinel, so null cannot be encoded. Wrap with NullableCoder.of(ByteArrayCoder.of()) if the pipeline genuinely produces null byte arrays.","triggerScenarios":"Encoding a null byte[] directly, or a PCollection<byte[]> containing null elements reaching serialization.","commonSituations":"Null byte arrays from I/O helpers (file/read returning null on failure), protobuf toByteArray() on a null message, manual coder use in tests or custom sinks.","solutions":["Filter null byte arrays with Filter.by(Objects::nonNull).","Use NullableCoder.of(ByteArrayCoder.of()) via setCoder() on the PCollection.","Substitute an empty array (new byte[0]) for null where acceptable.","Null-check before calling encode() in custom serialization code."],"exampleFix":"// before\nout.output(payload == null ? null : payload.toByteArray());\n// after\nout.output(payload == null ? new byte[0] : payload.toByteArray());","handlingStrategy":"validation","validationCode":"if (value == null) { throw new IllegalArgumentException(\"byte[] element is null; filter before encoding\"); }","typeGuard":"boolean isEncodable(byte[] v) { return v != null; }","tryCatchPattern":"try {\n  coder.encode(value, out, Context.OUTER);\n} catch (CoderException e) {\n  LOG.error(\"Null byte[] element\", e);\n  throw e;\n}","preventionTips":["Return new byte[0] instead of null from byte-producing helpers","Filter nulls before sinks and shuffles","Use NullableCoder.of(ByteArrayCoder.of()) for nullable binary data","Null-check protobuf/serialization helper outputs"],"tags":["java","apache-beam","coder","null","serialization"],"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"}