{"record":{"id":"661df87b474f5777","repo":"apache/beam","slug":"errorhandler-must-be-finalized-before-the-output-can-be","errorCode":null,"errorMessage":"ErrorHandler must be finalized before the output can be returned","messagePattern":"ErrorHandler must be finalized before the output can be returned","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/errorhandling/ErrorHandler.java","lineNumber":136,"sourceCode":"\n    @Override\n    public void addErrorCollection(PCollection<ErrorT> errorCollection) {\n      if (isClosed()) {\n        throw new IllegalStateException(\n            \"Error collections cannot be added after Error Handler is closed\");\n      }\n      errorCollections.add(errorCollection);\n    }\n\n    @Override\n    public boolean isClosed() {\n      return closed;\n    }\n\n    @Override\n    public @Nullable OutputT getOutput() {\n      if (!this.isClosed()) {\n        throw new IllegalStateException(\n            \"ErrorHandler must be finalized before the output can be returned\");\n      }\n      return sinkOutput;\n    }\n\n    @Override\n    public void close() {\n      if (closed) {\n        throw new IllegalStateException(\n            \"Error handler is already closed, and may not be closed twice\");\n      }\n      closed = true;\n      PCollection<ErrorT> flattened;\n      if (errorCollections.isEmpty()) {\n        LOG.info(\"Empty list of error pcollections passed to ErrorHandler.\");\n        flattened = pipeline.apply(Create.empty(coder));\n      } else {\n        flattened = PCollectionList.of(errorCollections).apply(Flatten.pCollections());","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/errorhandling/ErrorHandler.java#L118-L154","documentation":"ErrorHandler.getOutput throws IllegalStateException if the handler has not been finalized with close(). The sink output only exists after close() flattens the registered error collections and writes them, so Beam refuses to return a null/uninitialized output and forces the caller to close first.","triggerScenarios":"Calling errorHandler.getOutput() before errorHandler.close() — e.g. returning the error output PCollection from a translate()/expand() method before the handler's lifecycle completes, or forgetting to close the handler at all.","commonSituations":"IO connectors (BigQuery sink translation) calling getOutput during pipeline construction when the user never finalized the handler; users forgetting close() when managing the handler manually instead of try-with-resources.","solutions":["Call errorHandler.close() before requesting getOutput().","Use the handler within try-with-resources so close() is guaranteed to run before output use.","If you are an IO author, ensure the translation finalizes the handler before exposing its output."],"exampleFix":"// before\nPCollection<BadRecord> out = handler.getOutput(); // not closed\n// after\nhandler.close();\nPCollection<BadRecord> out = handler.getOutput();","handlingStrategy":"type-guard","validationCode":"if (errorHandler.isClosed()) { PCollection<OutputT> out = errorHandler.getOutput(); }","typeGuard":"boolean outputAvailable(ErrorHandler<?> h) {\n  try { return h.isClosed(); } catch (IllegalArgumentException e) { return false; }\n}","tryCatchPattern":"try {\n  output = errorHandler.getOutput();\n} catch (IllegalStateException e) {\n  errorHandler.close();\n  output = errorHandler.getOutput();\n}","preventionTips":["Always close the handler before reading its output","Use try-with-resources to guarantee finalization","In IO translations, finalize the handler before exposing output"],"tags":["java","apache-beam","error-handling","illegal-state","lifecycle"],"backgroundTag":"invalid-state-transition","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"}