apache/beam · error · IllegalStateException

%s does not support non zero terminator values. Received str

Error message

%s does not support non zero terminator values. Received stream with terminator %s.

What it means

IterableLikeCoder.decodeToIterable() is the extension hook for subclasses (ListCoder, IterableCoder, SetCoder, etc.). The base implementation throws IllegalStateException when the decoded stream carries a non-zero terminator, meaning the encoded stream was produced by an encoding scheme this coder does not understand. In practice this indicates byte-stream corruption or a coder mismatch between writer and reader.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/IterableLikeCoder.java:80

  }

  /**
   * Builds an instance of {@code IterableT}, this coder's associated {@link Iterable}-like subtype,
   * from a list of decoded elements.
   *
   * <p>Override {@link #decodeToIterable(List, long, InputStream)} if you need access to the
   * terminator value and the {@link InputStream}.
   */
  protected abstract IterableT decodeToIterable(List<T> decodedElements);

  /**
   * Builds an instance of {@code IterableT}, this coder's associated {@link Iterable}-like subtype,
   * from a list of decoded elements with the {@link InputStream} at the position where this coder
   * detected the end of the stream.
   */
  protected IterableT decodeToIterable(
      List<T> decodedElements, long terminatorValue, InputStream in) throws IOException {
    throw new IllegalStateException(
        String.format(
            "%s does not support non zero terminator values. Received stream with terminator %s.",
            iterableName, terminatorValue));
  }

  /////////////////////////////////////////////////////////////////////////////
  // Internal operations below here.

  private final Coder<T> elementCoder;
  private final String iterableName;

  protected IterableLikeCoder(Coder<T> elementCoder, String iterableName) {
    checkArgument(elementCoder != null, "element Coder for IterableLikeCoder must not be null");
    checkArgument(iterableName != null, "iterable name for IterableLikeCoder must not be null");
    this.elementCoder = elementCoder;
    this.iterableName = iterableName;
  }

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the same coder version encodes and decodes the data (pin Beam versions across write/read stages; drain or reset state when upgrading streaming jobs).
2. If you subclass IterableLikeCoder and intentionally emit non-zero terminators, override decodeToIterable(List, long, InputStream) to handle them.
3. Verify the encoded byte source is not truncated or corrupted; re-encode the data.

Example fix

// before (custom coder emits terminator but doesn't handle it)
// IllegalStateException at decode time
// after
@Override
protected IterableT decodeToIterable(List<T> decodedElements, long terminatorValue, InputStream in) {
  if (terminatorValue == EXPECTED_TERMINATOR) return build(decodedElements);
  throw new IllegalStateException("unexpected terminator " + terminatorValue);
}

try { coder.decode(in, context); } catch (IllegalStateException e) { log.error("Coder mismatch or corrupt stream", e); throw new IOException("Undecodable iterable stream", e); }

When it happens

Trigger: Decoding bytes with IterableLikeCoder (or a subclass) whose encoded stream ends with a non-zero terminator value; typically reading data encoded with a different or newer coder version, or reading from a truncated/corrupted source.

Common situations: Version-skew between job writer and runner (e.g. streaming pipelines upgraded mid-flight); manually concatenated encoded streams; implementing a custom IterableLikeCoder subclass without overriding decodeToIterable while emitting non-zero terminators.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• error when invoking Coder factory method
• cannot register Coder : does not have an accessible method n
• cannot register Coder : method named 'of' with arguments of
• cannot register Coder : method named 'of' with arguments of
• cannot register Coder : method named 'of' with arguments of

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/4ab2cad9ede21eb0. Report an issue: GitHub.