apache/beam · error · IllegalArgumentException

A list of URNs for overriding transforms was provided but th

Error message

A list of URNs for overriding transforms was provided but the pipeline did not contain any matching transforms. Either make sure to include at least one matching transform in the pipeline or avoid setting the 'transformsToOverride' PipelineOption. Provided list of URNs: 

What it means

TransformUpgrader checks that the URNs requested for override via the transformsToOverride PipelineOption actually matched transforms in the pipeline. If the URN list is non-empty but no pipeline transform matched any URN, it refuses to proceed because the override would be a silent no-op.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java:141

                      String schemaTransformId = schemaTransformPayload.getIdentifier();
                      if (urnsToOverride.contains(schemaTransformId)) {
                        return true;
                      }
                    } catch (InvalidProtocolBufferException e) {
                      throw new RuntimeException(e);
                    }
                  }

                  return false;
                })
            .map(
                entry -> {
                  return entry.getKey();
                })
            .collect(Collectors.toList());

    if (!urnsToOverride.isEmpty() && transformsToOverride.isEmpty()) {
      throw new IllegalArgumentException(
          "A list of URNs for overriding transforms was provided but the pipeline did not contain "
              + "any matching transforms. Either make sure to include at least one matching "
              + "transform in the pipeline or avoid setting the 'transformsToOverride' "
              + "PipelineOption. Provided list of URNs: "
              + urnsToOverride);
    }

    String serviceAddress;
    TransformServiceLauncher service = null;

    ExternalTranslationOptions externalTranslationOptions =
        options.as(ExternalTranslationOptions.class);
    if (externalTranslationOptions.getTransformServiceAddress() != null) {
      serviceAddress = externalTranslationOptions.getTransformServiceAddress();
    } else if (externalTranslationOptions.getTransformServiceBeamVersion() != null) {
      String projectName = UUID.randomUUID().toString();
      int port = findAvailablePort();
      service = TransformServiceLauncher.forProject(projectName, port, null);

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify each URN in transformsToOverride exists in the pipeline (e.g. via pipeline.toString() or a proto dump)
2. Remove the transformsToOverride option if no override is needed
3. Correct typo'd or outdated URNs to the actual transform URNs in the pipeline

Example fix

// before
--transformsToOverride=urn:beam:schematransform:org.apache.beam:my_transform:v1  // URN not in pipeline
// after
--transformsToOverride=urn:beam:schematransform:org.apache.beam:actual_urn:v1   // URN present in pipeline

// Before enabling overrides, confirm the pipeline actually contains the URNs:
String pipelineGraph = pipeline.toString(); // or traverse proto
for (String urn : options.as(TransformUpgraderOptions.class).getTransformsToOverride().values()) {
  if (!pipelineGraph.contains(urn)) {
    throw new IllegalStateException("transformsToOverride URN not present in pipeline: " + urn);
  }
}

try { pipeline.run(); } catch (IllegalArgumentException e) {
  if (e.getMessage().contains("transformsToOverride")) { /* correct or drop the URN list */ }
  else throw e;
}

When it happens

Trigger: Setting --transformsToOverride=urn:beam:... where no transform in the submitted pipeline has a matching URN (typo, URN from a different Beam version, or pipeline simply lacks that transform).

Common situations: Copy-pasting override URNs from docs/examples for a pipeline that doesn't contain those transforms; URN drift after a Beam version upgrade renamed schema-transform URNs.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• cannot call getPipelineOptions() in a null context
• Failed to convert PipelineOptions to JSON
• Either option TransformServiceAddress or option TransformSer
• Illegal access to pipeline after visitor traversal was compl
• Pipeline update will not be possible because the following t

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