{"record":{"id":"7db950843fae1fcc","repo":"apache/beam","slug":"cannot-encode-a-null-string","errorCode":null,"errorMessage":"cannot encode a null String","messagePattern":"cannot encode a null String","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StringUtf8Coder.java","lineNumber":74,"sourceCode":"    if (len < 0) {\n      throw new CoderException(\"Invalid encoded string length: \" + len);\n    }\n    byte[] bytes = new byte[len];\n    ByteStreams.readFully(dis, bytes);\n    return new String(bytes, StandardCharsets.UTF_8);\n  }\n\n  private StringUtf8Coder() {}\n\n  @Override\n  public void encode(String value, OutputStream outStream) throws IOException {\n    encode(value, outStream, Context.NESTED);\n  }\n\n  @Override\n  public void encode(String value, OutputStream outStream, Context context) throws IOException {\n    if (value == null) {\n      throw new CoderException(\"cannot encode a null String\");\n    }\n    if (context.isWholeStream) {\n      byte[] bytes = value.getBytes(StandardCharsets.UTF_8);\n      if (outStream instanceof ExposedByteArrayOutputStream) {\n        ((ExposedByteArrayOutputStream) outStream).writeAndOwn(bytes);\n      } else {\n        outStream.write(bytes);\n      }\n    } else {\n      writeString(value, outStream);\n    }\n  }\n\n  @Override\n  public String decode(InputStream inStream) throws IOException {\n    return decode(inStream, Context.NESTED);\n  }\n","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StringUtf8Coder.java#L56-L92","documentation":"StringUtf8Coder.encode has no encoding for null: it throws CoderException immediately because null String elements are not encodable under this coder. Beam coders generally reject null elements; use NullableCoder.of(StringUtf8Coder.of()) if nulls must round-trip.","triggerScenarios":"Calling StringUtf8Coder.of().encode(null, out, context) directly; a PCollection containing null Strings whose coder is plain StringUtf8Coder; schema'd rows with null string fields encoded by a non-nullable coder.","commonSituations":"Upstream transforms emitting nulls (empty lookups, missing JSON fields) flowing into a coded sink; code ported from languages where null strings are normal; data source changes making a previously non-null column nullable.","solutions":["Filter out or replace null strings before encoding (map null to \"\" or a sentinel).","Wrap the coder: NullableCoder.of(StringUtf8Coder.of()) and set it via setCoder().","Make the schema field @Nullable only if the pipeline uses a null-capable coder.","Fail fast upstream with a clear domain error so nulls are caught early."],"exampleFix":"// before\nStringUtf8Coder.of().encode(value, out, Context.OUTER);\n// after\nif (value == null) { value = \"\"; } // or use NullableCoder.of(StringUtf8Coder.of())\nStringUtf8Coder.of().encode(value, out, Context.OUTER);","handlingStrategy":"validation","validationCode":"if (value == null) {\n  throw new IllegalArgumentException(\"Cannot encode null String with StringUtf8Coder; provide a default or use NullableCoder\");\n}","typeGuard":"static boolean encodable(String s) { return s != null; }","tryCatchPattern":"try {\n  StringUtf8Coder.of().encode(value, out, ctx);\n} catch (CoderException e) {\n  throw new SerializationException(\"Null or unencodable String\", e);\n}","preventionTips":["Filter or default null strings before they reach a coded sink.","Prefer NullableCoder.of(StringUtf8Coder.of()) when nulls are legal data.","Audit data sources for nullable columns/fields.","Add unit tests covering null elements in coded PCollections."],"tags":["java","beam","coder","null-pointer","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-14T11:17:12.474Z"}