apache/beam · error · RuntimeException

Constructor method needs to be explicitly allowed

Error message

Constructor method ${nameFromPayload} needs to be explicitly allowed

What it means

The class declares a constructor method via @MultiLanguageConstructorMethod(name=...), but that name is not present in the expansion service's allowlist (isAllowedConstructorMethod). As a security guard against arbitrary code invocation, the provider throws RuntimeException instead of using the method.

Solutions

  1. Add the constructor method name to the expansion service's allowed constructor method configuration.
  2. Redeploy/restart the expansion service so the updated allowlist is loaded.
  3. If the method should not be restricted, ensure the annotation name matches the allowlist entry exactly (case-sensitive).
  4. Catch RuntimeException and return guidance to add the method to the allowlist.

Example fix

// before (service config)
allowedConstructorMethods: []
// after
allowedConstructorMethods:
  - myCustomConstructor
Defensive patterns

Strategy: validation

Validate before calling

if (!allowListClass.isAllowedConstructorMethod("myCustomConstructor")) throw new IllegalStateException("Add 'myCustomConstructor' to the expansion service allowlist");

Try / catch

try { method(payload, allowList); } catch (RuntimeException e) { if (e.getMessage().endsWith("needs to be explicitly allowed")) { /* fail with allowlist instructions */ } throw e; }

Prevention

When it happens

Trigger: isConstructorMethodForName matches an annotated method whose name equals payload.getConstructorMethod(), but the allowlist configured for the expansion service does not include that name.

Common situations: Deploying a new transform whose constructor method was added but the service's allowlist config was not updated; hardened expansion-service deployments that require explicit allowlisting; allowlist key typos.

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

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

Appendix: source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java:434

      throw new RuntimeException(
          "Could not find a matching constructor. When using field names, make sure they are "
              + "available in the compiled Java class.");
    } else if (mappingConstructors.size() != 1) {
      throw new RuntimeException(
          "Expected to find a single mapping constructor but found " + mappingConstructors.size());
    }
    return (Constructor<PTransform<InputT, OutputT>>) mappingConstructors.get(0);
  }

  private boolean isConstructorMethodForName(
      Method method, String nameFromPayload, AllowedClass allowListClass) {
    for (Annotation annotation : method.getAnnotations()) {
      if (annotation instanceof MultiLanguageConstructorMethod) {
        if (nameFromPayload.equals(((MultiLanguageConstructorMethod) annotation).name())) {
          if (allowListClass.isAllowedConstructorMethod(nameFromPayload)) {
            return true;
          } else {
            throw new RuntimeException(
                "Constructor method " + nameFromPayload + " needs to be explicitly allowed");
          }
        }
      }
    }
    if (method.getName().equals(nameFromPayload)) {
      if (allowListClass.isAllowedConstructorMethod(nameFromPayload)) {
        return true;
      } else {
        throw new RuntimeException(
            "Constructor method " + nameFromPayload + " needs to be explicitly allowed");
      }
    }
    return false;
  }

  private Method findMappingConstructorMethod(
      Method[] methods, JavaClassLookupPayload payload, AllowedClass allowListClass) {

View on GitHub (pinned to 12126d8942)