apache/beam · error · java.lang.IllegalArgumentException

Unknown allow-list version

Error message

Unknown allow-list version

What it means

JavaClassLookupTransformProvider's constructor validates that the provided AllowList proto's version equals the ALLOW_LIST_VERSION this provider understands; otherwise it throws IllegalArgumentException('Unknown allow-list version'). This guards against allow-list formats the provider cannot interpret.

Solutions

1. Regenerate the allow-list with the same Beam version as the expansion service
2. Upgrade the expansion service jar so ALLOW_LIST_VERSION matches the allow-list file
3. Inspect the allow-list file's version field and correct it to the expected constant
4. Remove a stale/hand-edited version field so defaults apply

Example fix

// before (allowlist.yaml)
version: 2
allowedClasses: [...]
// after
version: 1   # matches the service's ALLOW_LIST_VERSION
allowedClasses: [...]

AllowList al = parseAllowList(file);
if (!al.getVersion().equals(expectedVersion)) { throw new IllegalStateException("Allow-list version " + al.getVersion() + " unsupported"); }

try { provider = new JavaClassLookupTransformProvider(allowList); } catch (IllegalArgumentException e) { if (e.getMessage().equals("Unknown allow-list version")) { /* regenerate allow-list */ } throw e; }

When it happens

Trigger: Constructing JavaClassLookupTransformProvider with an AllowList whose getVersion() differs from the provider's compiled-in ALLOW_LIST_VERSION — e.g., allow-list file generated by a different Beam version.

Common situations: Expansion service and allow-list JSON/proto produced by mismatched Beam versions; hand-edited allow-list adding a version field; upgraded service still loading an old allow-list file.

Related errors

• A list of URNs for overriding transforms was provided but…
• A cannot be expanded
• A transform cannot be initiated using the provided config…
• AVRO schema doesn't match row schema. Row schema
• BigQuery data contained value

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

Appendix: source

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

 * and builder methods.
 *
 * @param <InputT> input {@link PInput} type of the transform
 * @param <OutputT> output {@link POutput} type of the transform
 */
@SuppressFBWarnings("UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD")
class JavaClassLookupTransformProvider<InputT extends PInput, OutputT extends POutput>
    implements TransformProvider<PInput, POutput> {

  public static final String ALLOW_LIST_VERSION = "v1";

  public static final Pattern FIELD_NAME_IGNORE_PATTERN = Pattern.compile("ignore[0-9]+");

  private static final SchemaRegistry SCHEMA_REGISTRY = SchemaRegistry.createDefault();
  private final AllowList allowList;

  public JavaClassLookupTransformProvider(AllowList allowList) {
    if (!allowList.getVersion().equals(ALLOW_LIST_VERSION)) {
      throw new IllegalArgumentException("Unknown allow-list version");
    }
    this.allowList = allowList;
  }

  @SuppressWarnings("argument")
  @Override
  public PTransform<PInput, POutput> getTransform(FunctionSpec spec, PipelineOptions options) {
    JavaClassLookupPayload payload;
    try {
      payload = JavaClassLookupPayload.parseFrom(spec.getPayload());
    } catch (InvalidProtocolBufferException e) {
      throw new IllegalArgumentException(
          "Invalid payload type for URN " + getUrn(ExpansionMethods.Enum.JAVA_CLASS_LOOKUP), e);
    }

    String className = payload.getClassName();
    try {
      AllowedClass allowlistClass = allowList.getAllowedClass(className);

View on GitHub (pinned to 12126d8942)