{"record":{"id":"08ba27e0c635a9d4","repo":"apache/beam","slug":"encountered-checked-exception-when-constructing-an-instance","errorCode":null,"errorMessage":"Encountered checked exception when constructing an instance from factory method %s#%s(%s)","messagePattern":"Encountered checked exception when constructing an instance from factory method (.+?)#(.+?)\\((.+?)\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java","lineNumber":226,"sourceCode":"\n      if (!method.isAccessible()) {\n        method.setAccessible(true);\n      }\n\n      Object[] args = arguments.toArray(new Object[arguments.size()]);\n      return type.cast(method.invoke(null, args));\n\n    } catch (NoSuchMethodException e) {\n      throw new RuntimeException(\n          String.format(\n              \"Unable to find factory method %s#%s(%s)\",\n              factoryClass.getSimpleName(), methodName, Joiner.on(\", \").join(types)));\n    } catch (InvocationTargetException e) {\n      if (e.getTargetException() instanceof RuntimeException) {\n        // If underlying exception is unchecked re-raise it as-is\n        throw (RuntimeException) e.getTargetException();\n      }\n      throw new RuntimeException(\n          String.format(\n              \"Encountered checked exception when constructing an instance from factory method %s#%s(%s)\",\n              factoryClass.getSimpleName(), methodName, Joiner.on(\", \").join(types)),\n          e.getTargetException());\n    } catch (IllegalAccessException e) {\n      throw new RuntimeException(\n          String.format(\n              \"Failed to construct instance from factory method %s#%s(%s) due to access restriction\",\n              factoryClass.getSimpleName(), methodName, Joiner.on(\", \").join(types)),\n          e);\n    }\n  }\n\n  private T buildFromConstructor(Class<?>[] types) {\n    checkState(factoryClass != null);\n\n    try {\n      Constructor<?> constructor = factoryClass.getDeclaredConstructor(types);","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java#L208-L244","documentation":"InstanceBuilder.buildFromMethod() wraps InvocationTargetException where the target is a checked exception into RuntimeException 'Encountered checked exception when constructing an instance from factory method %s#%s(%s)'. The real cause is the checked exception thrown by the factory method body itself.","triggerScenarios":"The resolved static factory method declares and throws a checked exception (e.g. IOException) during instance creation; runtime exceptions are rethrown as-is, so only checked ones produce this message.","commonSituations":"Factory method performs I/O or parsing that fails (bad config file, missing resource); constructor of the target class validates input and throws a checked exception.","solutions":["Read getCause()/e.getTargetException() to find the real checked exception and fix its root cause","Fix the invalid input (file, config, resource) the factory method consumes","Pre-validate inputs before calling build()","If you own the factory method, throw unchecked exceptions or handle the checked one internally"],"exampleFix":"// before: factory throws checked IOException from bad path\nInstanceBuilder.fromClassName(...).fromFactoryMethod(\"fromFile\", \"/missing.yaml\").build();\n// after: validate first\nif (!Files.exists(path)) throw new IllegalArgumentException(\"missing: \" + path);\nInstanceBuilder.fromClassName(...).fromFactoryMethod(\"fromFile\", path.toString()).build();","handlingStrategy":"try-catch","validationCode":"if (inputFile == null || !Files.exists(inputFile)) { throw new IllegalArgumentException(\"factory input missing\"); }","typeGuard":null,"tryCatchPattern":"try { instance = builder.build(); } catch (RuntimeException e) { Throwable root = e.getCause(); log.error(\"factory threw {}\", root); throw root instanceof RuntimeException ? (RuntimeException) root : e; }","preventionTips":["Always inspect getCause() — the real failure is the factory's checked exception","Pre-validate resources/inputs the factory consumes","Prefer factory methods that fail fast with clear messages"],"tags":["java","reflection","checked-exception","factory-method"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}