apache/beam · error · RuntimeException

Encountered checked exception when constructing an instance

Error message

Encountered checked exception when constructing an instance from factory method %s#%s(%s)

What it means

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.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java:226

      if (!method.isAccessible()) {
        method.setAccessible(true);
      }

      Object[] args = arguments.toArray(new Object[arguments.size()]);
      return type.cast(method.invoke(null, args));

    } catch (NoSuchMethodException e) {
      throw new RuntimeException(
          String.format(
              "Unable to find factory method %s#%s(%s)",
              factoryClass.getSimpleName(), methodName, Joiner.on(", ").join(types)));
    } catch (InvocationTargetException e) {
      if (e.getTargetException() instanceof RuntimeException) {
        // If underlying exception is unchecked re-raise it as-is
        throw (RuntimeException) e.getTargetException();
      }
      throw new RuntimeException(
          String.format(
              "Encountered checked exception when constructing an instance from factory method %s#%s(%s)",
              factoryClass.getSimpleName(), methodName, Joiner.on(", ").join(types)),
          e.getTargetException());
    } catch (IllegalAccessException e) {
      throw new RuntimeException(
          String.format(
              "Failed to construct instance from factory method %s#%s(%s) due to access restriction",
              factoryClass.getSimpleName(), methodName, Joiner.on(", ").join(types)),
          e);
    }
  }

  private T buildFromConstructor(Class<?>[] types) {
    checkState(factoryClass != null);

    try {
      Constructor<?> constructor = factoryClass.getDeclaredConstructor(types);

View on GitHub (pinned to 12126d8942)

Solutions

1. Read getCause()/e.getTargetException() to find the real checked exception and fix its root cause
2. Fix the invalid input (file, config, resource) the factory method consumes
3. Pre-validate inputs before calling build()
4. If you own the factory method, throw unchecked exceptions or handle the checked one internally

Example fix

// before: factory throws checked IOException from bad path
InstanceBuilder.fromClassName(...).fromFactoryMethod("fromFile", "/missing.yaml").build();
// after: validate first
if (!Files.exists(path)) throw new IllegalArgumentException("missing: " + path);
InstanceBuilder.fromClassName(...).fromFactoryMethod("fromFile", path.toString()).build();

if (inputFile == null || !Files.exists(inputFile)) { throw new IllegalArgumentException("factory input missing"); }

try { instance = builder.build(); } catch (RuntimeException e) { Throwable root = e.getCause(); log.error("factory threw {}", root); throw root instanceof RuntimeException ? (RuntimeException) root : e; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unable to find factory method %s#%s(%s)
• error when invoking Coder factory method
• cannot register Coder : does not have an accessible method n
• cannot register Coder : method named 'of' with arguments of
• cannot register Coder : method named 'of' with arguments of

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/08ba27e0c635a9d4. Report an issue: GitHub.