apache/beam · error · CoderException

cannot encode a null Integer

Error message

cannot encode a null Integer

What it means

TextualIntegerCoder encodes Integers as their decimal string form (delegating to StringUtf8Coder) and does not support null, since there is no textual form for null. It throws CoderException; wrap with NullableCoder if nulls must round-trip.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/TextualIntegerCoder.java:50

    return new TextualIntegerCoder();
  }

  /////////////////////////////////////////////////////////////////////////////

  private static final TypeDescriptor<Integer> TYPE_DESCRIPTOR = new TypeDescriptor<Integer>() {};

  protected TextualIntegerCoder() {}

  @Override
  public void encode(Integer value, OutputStream outStream) throws IOException, CoderException {
    encode(value, outStream, Context.NESTED);
  }

  @Override
  public void encode(Integer value, OutputStream outStream, Context context)
      throws IOException, CoderException {
    if (value == null) {
      throw new CoderException("cannot encode a null Integer");
    }
    String textualValue = value.toString();
    StringUtf8Coder.of().encode(textualValue, outStream, context);
  }

  @Override
  public Integer decode(InputStream inStream) throws IOException, CoderException {
    return decode(inStream, Context.NESTED);
  }

  @Override
  public Integer decode(InputStream inStream, Context context) throws IOException, CoderException {
    String textualValue = StringUtf8Coder.of().decode(inStream, context);
    try {
      return Integer.valueOf(textualValue);
    } catch (NumberFormatException exn) {
      throw new CoderException("error when decoding a textual integer", exn);
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Coalesce nulls to a default (e.g. 0 or -1) before encoding.
2. Wrap with NullableCoder.of(TextualIntegerCoder.of()) and set it as the PCollection coder.
3. Filter null elements before the sink/encode step.
4. Fix the upstream transform to produce a non-null value or handle Optional explicitly.

Example fix

// before
TextualIntegerCoder.of().encode(value, out, Context.OUTER);
// after
int safe = value == null ? 0 : value;
TextualIntegerCoder.of().encode(safe, out, Context.OUTER);

if (value == null) {
  throw new IllegalArgumentException("Cannot encode null Integer with TextualIntegerCoder; provide a default or use NullableCoder");
}

static boolean encodable(Integer v) { return v != null; }

try {
  TextualIntegerCoder.of().encode(value, out, ctx);
} catch (CoderException e) {
  throw new SerializationException("Null or unencodable Integer", e);
}

When it happens

Trigger: Calling TextualIntegerCoder.of().encode(null, out, context) directly; a PCollection<Integer> containing null values encoded with TextualIntegerCoder (counts or lookups that produced null); text sinks fed null integers.

Common situations: Side inputs or lookup joins returning null for missing keys; parse transformations yielding null Integer that are then written through the coder; refactors turning boxed defaults into nulls.

Related errors

• cannot encode a null String
• cannot encode a null ValueKind
• Cannot encode null window
• {errorContext}: unable to encode value {value} using {coder}
• Unable to encode constant members of ParamWindowedValueCoder

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