apache/beam · error · NullPointerException

.exceptionsVia() is required

Error message

.exceptionsVia() is required

What it means

MapWithFailures' expansion requires an exception handler configured via .exceptionsVia(); the transform must know where to send failures. If exceptionsVia() was never called on the builder, exceptionHandler is null and expand() throws NullPointerException with the message '.exceptionsVia() is required'.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/SimpleMapWithFailures.java:55

  private final String transformName;

  SimpleMapWithFailures(
      String transformName,
      Contextful<Fn<InputT, OutputT>> fn,
      TypeDescriptor<OutputT> outputType,
      @Nullable ProcessFunction<ExceptionElement<InputT>, FailureT> exceptionHandler,
      TypeDescriptor<FailureT> failureType) {
    this.transformName = transformName;
    this.fn = fn;
    this.outputType = outputType;
    this.exceptionHandler = exceptionHandler;
    this.failureType = failureType;
  }

  @Override
  public WithFailures.Result<PCollection<OutputT>, FailureT> expand(PCollection<InputT> input) {
    if (exceptionHandler == null) {
      throw new NullPointerException(".exceptionsVia() is required");
    }
    return input.apply(
        transformName,
        MapElements.into(outputType)
            .via(fn)
            .exceptionsInto(failureType)
            .exceptionsVia(exceptionHandler));
  }

  /**
   * Returns a {@code PTransform} that catches exceptions raised while mapping elements, passing the
   * raised exception instance and the input element being processed through the given {@code
   * exceptionHandler} and emitting the result to a failure collection.
   */
  public SimpleMapWithFailures<InputT, OutputT, FailureT> exceptionsVia(
      ProcessFunction<ExceptionElement<InputT>, FailureT> exceptionHandler) {
    return new SimpleMapWithFailures<>(
        transformName, fn, outputType, exceptionHandler, failureType);

View on GitHub (pinned to 12126d8942)

Solutions

1. Call .exceptionsVia(...) with an ExceptionHandler before expanding the transform
2. If failures are not wanted, use plain MapElements without the WithFailures API instead
3. Ensure the code path that builds the transform always sets a handler

Example fix

// before
MapWithFailures<String, Integer> map = MapElements.into(integers()).via(fn).exceptionsInto(failureType); // then input.apply(map) without handler
// after
PCollection<Integer> ok = input.apply(MapElements.into(integers()).via(fn)
    .exceptionsInto(TypeDescriptors.strings())
    .exceptionsVia(new InboundEmergencyHandler()));

if (exceptionHandler == null) { throw new IllegalStateException("call .exceptionsVia() before expanding MapWithFailures"); }

try { return input.apply(mapWithFailures); } catch (NullPointerException e) { throw new IllegalStateException("MapWithFailures requires .exceptionsVia()", e); }

When it happens

Trigger: Building a SimpleMapWithFailures (or calling MapElements...exceptionsInto(...)) and expanding the PTransform without invoking .exceptionsVia(handler) on it.

Common situations: Constructing the transform programmatically (e.g. in library code) and forgetting the handler step; copying pipeline code and dropping the exceptionsVia line; wiring failures conditionally and leaving it null in one branch.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Only %s objects with the same window supplier are compatible
• ApproximateUnique.PerKey needs an estimation error between 1
• ApproximateUnique.PerKey requires its input to use KvCoder
• Cannot provide coder for elements of Create: For their commo
• Cannot provide coder for elements of Create: For their commo

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