apache/beam · error · RuntimeException

Failed to construct instance from factory method

Error message

Failed to construct instance from factory method %s#%s(%s) due to access restriction

What it means

InstanceBuilder.buildFromMethod() catches IllegalAccessException and throws RuntimeException 'Failed to construct instance ... due to access restriction'. This occurs when Java access control prevents invoking the otherwise-matching static factory method.

Solutions

1. Make the factory method and its class public
2. Under JPMS, open/export the containing package or add --add-opens/--add-exports JVM flags
3. Avoid shaded/relocated classes in the builder configuration
4. Check the module-info/package-private modifiers of the factory class

Example fix

// before
class MyFactory { static MyThing of(String s) {...} }
// after
public class MyFactory { public static MyThing of(String s) {...} }

int mods = factoryClass.getModifiers() | factoryMethod.getModifiers();
if (!java.lang.reflect.Modifier.isPublic(mods)) { throw new IllegalStateException("factory method/class must be public"); }

try { instance = builder.build(); } catch (RuntimeException e) { if (e.getMessage().contains("access restriction")) { /* fix visibility or JPMS exports */ } throw e; }

When it happens

Trigger: The factory method or its class is package-private/private or defined in a non-exported module/package, while the caller has insufficient access (e.g. JPMS strong encapsulation, reflection without setAccessible).

Common situations: Using --add-opens-less environments under Java 9+ module system; shading moved classes into packages where the method is no longer accessible; passing an inner class's private factory method.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• ${e.getMessage()}
• No code generation strategy available
• No code generation strategy available
• A method marked with SchemaCreate in class
• AutoValue builder class

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

Appendix: source

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

      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);

      checkState(
          type.isAssignableFrom(factoryClass),
          "Instance type %s must be assignable to %s",
          factoryClass.getName(),
          type.getSimpleName());

View on GitHub (pinned to 12126d8942)