apache/beam · error · IllegalArgumentException

Found two matching allowlist classes

Error message

Found two matching allowlist classes ${allowlistClass} and ${cls}

What it means

getAllowedClass scans the allowlist for a class matching the requested name (or assignable type) and found two distinct AllowedClass entries that both match. The allowlist itself is at fault: it declares overlapping/ambiguous entries (e.g. both a concrete class and an assignable supertype), so the lookup cannot choose one deterministically.

Solutions

Remove duplicate/overlapping entries so each class matches exactly one allowlist entry.
Keep wildcard and specific entries mutually exclusive.
Deduplicate allowedClasses at generation time before feeding the service.
Identify the two conflicting entries from the message and drop the redundant one.

Example fix

# before
allowedClasses:
  - className: org.example.*
  - className: org.example.Foo
# after
allowedClasses:
  - className: org.example.*

Defensive patterns

Strategy: validation

Validate before calling

Set<String> seen = new HashSet<>();
for (AllowedClass ac : provider.getAllowedClasses()) {
  if (!seen.add(ac.toString())) throw new IllegalStateException("Duplicate allowlist entry: " + ac);
}

Type guard

boolean isUnambiguous(AllowList list, String className) { return list.getAllowedClasses().stream().filter(c -> c.isAllowedClass(className)).count() <= 1; }

Try / catch

try { AllowedClass ac = provider.getAllowedClass(className); } catch (IllegalArgumentException e) { log.error("Ambiguous allowlist: {}", e.getMessage()); throw new ConfigConflictException(e); }

Prevention

Run a pre-flight ambiguity check on startup
Prefer a single wildcard over wildcard+specific pairs
Deduplicate auto-generated allowlists before deploy
Review merged allowlist files for overlap

When it happens

Trigger: Allowlist contains duplicate className entries, or two entries whose isAllowedClass both match the requested class (e.g. 'org.example.Foo' and 'org.example.*' both defined).

Common situations: Merging two allowlist files with overlapping packages; adding a specific class already covered by a wildcard; auto-generated config duplication.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

                          }
                          return AllowedClass.create(
                              className, allowedBuilderMethods, allowedConstructorMethods);
                        })
                    .collect(Collectors.toList());
      }
      return AllowList.create(version, allowedClasses);
    }

    public abstract String getVersion();

    public abstract List<AllowedClass> getAllowedClasses();

    public AllowedClass getAllowedClass(String className) {
      AllowedClass allowlistClass = null;
      for (AllowedClass cls : getAllowedClasses()) {
        if (cls.isAllowedClass(className)) {
          if (allowlistClass != null) {
            throw new IllegalArgumentException(
                "Found two matching allowlist classes " + allowlistClass + " and " + cls);
          }
          allowlistClass = cls;
        }
      }
      if (allowlistClass == null) {
        throw new UnsupportedOperationException(
            "The provided allow list does not enable expanding a transform class by the name "
                + className
                + ".");
      }
      return allowlistClass;
    }

    static AllowList create(String version, List<AllowedClass> allowedClasses) {
      if (allowedClasses == null) {
        allowedClasses = new ArrayList<>();
      }

View on GitHub (pinned to 12126d8942)