{"record":{"id":"060bbf39fd0c30c5","repo":"apache/beam","slug":"nullablecoder-expects-either-a-byte-valued-0-null-or-1","errorCode":null,"errorMessage":"NullableCoder expects either a byte valued 0 (null) or 1 (present), got %s","messagePattern":"NullableCoder expects either a byte valued 0 \\(null\\) or 1 \\(present\\), got (.+?)","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/NullableCoder.java","lineNumber":89,"sourceCode":"    } else {\n      outStream.write(ENCODE_PRESENT);\n      valueCoder.encode(value, outStream, context);\n    }\n  }\n\n  @Override\n  public @Nullable T decode(InputStream inStream) throws IOException, CoderException {\n    return decode(inStream, Context.NESTED);\n  }\n\n  @Override\n  public @Nullable T decode(InputStream inStream, Context context)\n      throws IOException, CoderException {\n    int b = inStream.read();\n    if (b == ENCODE_NULL) {\n      return null;\n    } else if (b != ENCODE_PRESENT) {\n      throw new CoderException(\n          String.format(\n              \"NullableCoder expects either a byte valued %s (null) or %s (present), got %s\",\n              ENCODE_NULL, ENCODE_PRESENT, b));\n    }\n    return valueCoder.decode(inStream, context);\n  }\n\n  @Override\n  public List<Coder<T>> getCoderArguments() {\n    return ImmutableList.of(valueCoder);\n  }\n\n  /**\n   * {@code NullableCoder} is deterministic if the nested {@code Coder} is.\n   *\n   * <p>{@inheritDoc}\n   */\n  @Override","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/NullableCoder.java#L71-L107","documentation":"NullableCoder's decode() reads one byte that must be 0 (ENCODE_NULL) or 1 (ENCODE_PRESENT). Any other value means the stream is corrupt, truncated, or was not written by NullableCoder, so decoding cannot proceed. This is a data-integrity failure, not an application-logic error.","triggerScenarios":"Decoding a byte stream whose first byte is not 0x00 or 0x01: e.g. stream produced by a different coder, an out-of-sync InputStream offset, byte corruption, or version mismatch between writer and reader coder.","commonSituations":"Changing a pipeline's coder (e.g. adding/removing NullableCoder) without re-running from scratch, so old checkpoints/state are decoded with the new coder; byte-stream truncation; manual wire-format fiddling.","solutions":["Re-run the pipeline from a source rather than resuming from state encoded with an incompatible coder version","Verify the InputStream is positioned exactly at the start of the NullableCoder-encoded value (no earlier fields were skipped)","Check that the writer and reader use the same coder version (same Beam release for state/backup data)"],"exampleFix":"// before\nCoder<T> coder = myCoder; // changed from NullableCoder.of(...), old state unreadable\n// after\n// re-run pipeline from source, or keep the same coder:\nCoder<T> coder = NullableCoder.of(innerCoder); // matches previously written bytes","handlingStrategy":"try-catch","validationCode":"// No pre-call check possible on a raw stream; verify the coder matches the writer's coder version","typeGuard":"null","tryCatchPattern":"try { T v = nullableCoder.decode(in, Context.OUTER); } catch (CoderException e) { /* treat stream as corrupt: re-read from source */ }","preventionTips":["Keep coder versions stable across pipeline deploys for stateful/streaming jobs","Never hand-edit or partially read encoded byte streams","Re-run from source rather than decoding legacy state after coder changes"],"tags":["java","beam","coders","deserialization"],"backgroundTag":"unexpected-response-shape","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"}