{"record":{"id":"bdd824966492d039","repo":"apache/beam","slug":"unexpected-exception-fetching-database-schema","errorCode":null,"errorMessage":"Unexpected exception fetching database schema.","messagePattern":"Unexpected exception fetching database schema\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/debezium/src/main/java/org/apache/beam/io/debezium/KafkaSourceConsumerFn.java","lineNumber":180,"sourceCode":"      int loops = 0;\n      while (records.size() == 0) {\n        if (loops > 3) {\n          throw new RuntimeException(\"could not fetch database schema\");\n        }\n        records = task.poll();\n        // Waiting for the Database snapshot to finish.\n        Thread.sleep(2000);\n        loops += 1;\n      }\n      task.stop();\n      connector.stop();\n      return records.get(0);\n    } catch (NoSuchMethodException\n        | InterruptedException\n        | InvocationTargetException\n        | IllegalAccessException\n        | InstantiationException e) {\n      throw new RuntimeException(\"Unexpected exception fetching database schema.\", e);\n    }\n  }\n\n  void register(RestrictionTracker<OffsetHolder, Map<String, Object>> tracker) {\n    restrictionTrackers.put(this.getHashCode(), tracker);\n  }\n\n  void reset() {\n    restrictionTrackers.remove(this.getHashCode());\n  }\n\n  @GetInitialWatermarkEstimatorState\n  public Instant getInitialWatermarkEstimatorState(@Timestamp Instant currentElementTimestamp) {\n    return currentElementTimestamp;\n  }\n\n  @NewWatermarkEstimator\n  public WatermarkEstimator<Instant> newWatermarkEstimator(","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/debezium/src/main/java/org/apache/beam/io/debezium/KafkaSourceConsumerFn.java#L162-L198","documentation":"getOneRecord reflectsively instantiates and drives a Debezium connector task. Reflective calls declare checked exceptions (NoSuchMethodException, InterruptedException, InvocationTargetException, IllegalAccessException, InstantiationException); any of these is wrapped in this RuntimeException. It signals a harness/reflection problem rather than a database failure.","triggerScenarios":"The Connector/Task class lacks an expected method or no-arg constructor, the polling thread is interrupted, or reflection-based invocation fails while fetching one record.","commonSituations":"Debezium version incompatibility (class/API changed so reflection targets are missing), classpath conflicts with multiple Debezium versions, thread interruption during pipeline shutdown.","solutions":["Align the Debezium connector version with the one Apache Beam's DebeziumIO was built against.","Check the classpath for duplicate/conflicting Debezium artifacts (mvn dependency:tree).","Read the cause chain (the wrapped exception) to identify which reflective call failed.","Avoid interrupting the worker thread mid-schema-fetch; retry the pipeline."],"exampleFix":"// before\ndebeziumVersion = 1.9.7.Final // with Beam built for 1.6.x\n// after\nmatch the io.debezium version to your Beam release's dependency","handlingStrategy":"try-catch","validationCode":"Class.forName(\"io.debezium.connector.mysql.MySqlConnectorTask\", true, loader);\n// fails fast if Debezium classes are absent/conflicting","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.run().waitUntilFinish();\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Unexpected exception fetching database schema\")) {\n    LOG.error(\"Check Debezium version/classpath; cause:\", e.getCause());\n  }\n}","preventionTips":["Match io.debezium version to your Beam release's dependency","Run mvn dependency:tree to detect conflicting Debezium artifacts","Keep the schema-fetch phase isolated from shutdown/interruption"],"tags":["java","reflection","debezium","classpath","apache-beam"],"backgroundTag":"missing-dependency","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"}