{"record":{"id":"1d3e6e0372d3a013","repo":"apache/beam","slug":"encountered-bad-record","errorCode":null,"errorMessage":"Encountered Bad Record: ","messagePattern":"Encountered Bad Record: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/errorhandling/BadRecordRouter.java","lineNumber":92,"sourceCode":"        BoundedWindow window)\n        throws Exception {\n      route(record, exception);\n    }\n\n    private <RecordT> void route(RecordT record, @Nullable Exception exception) throws Exception {\n      if (exception != null) {\n        throw exception;\n      } else {\n        Preconditions.checkArgumentNotNull(record);\n        String encodedRecord =\n            BadRecord.Record.builder()\n                .addHumanReadableJson(record)\n                .build()\n                .getHumanReadableJsonRecord();\n        if (encodedRecord == null) {\n          encodedRecord = \"Unable to serialize bad record\";\n        }\n        throw new RuntimeException(\"Encountered Bad Record: \" + encodedRecord);\n      }\n    }\n  }\n\n  class RecordingBadRecordRouter implements BadRecordRouter {\n\n    @Override\n    public <RecordT> void route(\n        MultiOutputReceiver outputReceiver,\n        RecordT record,\n        @Nullable Coder<RecordT> coder,\n        @Nullable Exception exception,\n        String description)\n        throws Exception {\n      outputReceiver\n          .get(BAD_RECORD_TAG)\n          .output(BadRecord.fromExceptionInformation(record, coder, exception, description));\n    }","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/errorhandling/BadRecordRouter.java#L74-L110","documentation":"BadRecordRouter.route throws this when a record fails processing AND the error handler is the default 'throw' handler (no BadRecordErrorHandler configured). The bad record's human-readable JSON (or a fallback string if serialization fails) is appended to the message and the RuntimeException fails the pipeline, which is Beam's fail-fast default for error handling.","triggerScenarios":"An exception is thrown while processing an element in a transform that supports bad-record routing (e.g. BigQueryIO, FileIO reads) and no .withErrorHandling(...) BadRecordErrorHandler was configured, or the configured handler's output was not wired, leaving the throwing router active.","commonSituations":"Malformed input records (bad JSON, wrong schema) in BigQuery Storage Read/Write or FileIO pipelines where developers expected errors to be routed to an error PCollection but forgot to attach the error handler.","solutions":["Attach a BadRecordErrorHandler via the IO's error-handling API (e.g. .withExceptionHandling / ErrorHandling options) so bad records go to an error PCollection instead of throwing.","Fix or filter the malformed records upstream so the exception never occurs.","Inspect the record JSON in the message to identify the specific bad element and its parse failure."],"exampleFix":"// before\nBigQueryIO.readTableRows().from(table) // throws on bad record\n// after\nErrorHandle<BadRecord> errorHandler = ErrorHandler.getDefaultBadRecordErrorHandler(...);\nBigQueryIO.readTableRows().from(table).withBadRecordErrorHandler(errorHandler)","handlingStrategy":"validation","validationCode":"// Before running, ensure an error handler is attached when the IO supports it:\nboolean handlerAttached = io != null && io.getBadRecordErrorHandler() != null;\nif (!handlerAttached) { throw new IllegalStateException(\"Bad records will fail the pipeline\"); }","typeGuard":"null","tryCatchPattern":"try {\n  pipeline.run().waitUntilFinish();\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Encountered Bad Record:\")) {\n    LOG.error(\"Bad record failed pipeline: {}\", e.getMessage());\n  }\n}","preventionTips":["Always configure a BadRecordErrorHandler for IOs reading untrusted/malformed input","Validate input records upstream before pipeline execution","Route bad records to a dead-letter PCollection in production pipelines"],"tags":["java","apache-beam","error-handling","bad-record","pipeline-failure"],"backgroundTag":"unexpected-response-shape","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}