{"record":{"id":"f88dd8b6a897f02a","repo":"apache/beam","slug":"exceptionsvia-is-required","errorCode":null,"errorMessage":".exceptionsVia() is required","messagePattern":"\\.exceptionsVia\\(\\) is required","errorType":"exception","errorClass":"NullPointerException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/SimpleMapWithFailures.java","lineNumber":55,"sourceCode":"  private final String transformName;\n\n  SimpleMapWithFailures(\n      String transformName,\n      Contextful<Fn<InputT, OutputT>> fn,\n      TypeDescriptor<OutputT> outputType,\n      @Nullable ProcessFunction<ExceptionElement<InputT>, FailureT> exceptionHandler,\n      TypeDescriptor<FailureT> failureType) {\n    this.transformName = transformName;\n    this.fn = fn;\n    this.outputType = outputType;\n    this.exceptionHandler = exceptionHandler;\n    this.failureType = failureType;\n  }\n\n  @Override\n  public WithFailures.Result<PCollection<OutputT>, FailureT> expand(PCollection<InputT> input) {\n    if (exceptionHandler == null) {\n      throw new NullPointerException(\".exceptionsVia() is required\");\n    }\n    return input.apply(\n        transformName,\n        MapElements.into(outputType)\n            .via(fn)\n            .exceptionsInto(failureType)\n            .exceptionsVia(exceptionHandler));\n  }\n\n  /**\n   * Returns a {@code PTransform} that catches exceptions raised while mapping elements, passing the\n   * raised exception instance and the input element being processed through the given {@code\n   * exceptionHandler} and emitting the result to a failure collection.\n   */\n  public SimpleMapWithFailures<InputT, OutputT, FailureT> exceptionsVia(\n      ProcessFunction<ExceptionElement<InputT>, FailureT> exceptionHandler) {\n    return new SimpleMapWithFailures<>(\n        transformName, fn, outputType, exceptionHandler, failureType);","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/SimpleMapWithFailures.java#L37-L73","documentation":"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'.","triggerScenarios":"Building a SimpleMapWithFailures (or calling MapElements...exceptionsInto(...)) and expanding the PTransform without invoking .exceptionsVia(handler) on it.","commonSituations":"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.","solutions":["Call .exceptionsVia(...) with an ExceptionHandler before expanding the transform","If failures are not wanted, use plain MapElements without the WithFailures API instead","Ensure the code path that builds the transform always sets a handler"],"exampleFix":"// before\nMapWithFailures<String, Integer> map = MapElements.into(integers()).via(fn).exceptionsInto(failureType); // then input.apply(map) without handler\n// after\nPCollection<Integer> ok = input.apply(MapElements.into(integers()).via(fn)\n    .exceptionsInto(TypeDescriptors.strings())\n    .exceptionsVia(new InboundEmergencyHandler()));","handlingStrategy":"validation","validationCode":"if (exceptionHandler == null) { throw new IllegalStateException(\"call .exceptionsVia() before expanding MapWithFailures\"); }","typeGuard":null,"tryCatchPattern":"try { return input.apply(mapWithFailures); } catch (NullPointerException e) { throw new IllegalStateException(\"MapWithFailures requires .exceptionsVia()\", e); }","preventionTips":["Always chain .exceptionsVia(...) immediately after .exceptionsInto(...)","Encapsulate WithFailures wiring in one factory method so the handler is never omitted","Review builder-style pipelines for missing terminal configuration calls"],"tags":["java","apache-beam","pipeline-construction","missing-argument","null-pointer"],"backgroundTag":"missing-required-argument","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"}