apache/beam · error · IllegalArgumentException

Unknown URN %s

Error message

Unknown URN %s

What it means

PTransformFunctionRegistry translates an execution-state URN (e.g. process-start/finish msecs monitoring URNs) into an ExecutionStateTracker state name in its constructor. If the URN is not one of the known execution-state URNs, the constructor throws IllegalArgumentException('Unknown URN %s'), since a metrics counter cannot be built for an unrecognized state.

Source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/data/PTransformFunctionRegistry.java:81

  /**
   * Construct the registry to run for either start or finish bundle functions.
   *
   * @param shortIds - Provides short ids for {@link MonitoringInfo}.
   * @param stateTracker - The tracker to enter states in order to calculate execution time metrics.
   * @param executionStateUrn - The URN for the execution state .
   */
  public PTransformFunctionRegistry(
      ShortIdMap shortIds, ExecutionStateTracker stateTracker, String executionStateUrn) {
    switch (executionStateUrn) {
      case Urns.START_BUNDLE_MSECS:
        stateName = org.apache.beam.runners.core.metrics.ExecutionStateTracker.START_STATE_NAME;
        break;
      case Urns.FINISH_BUNDLE_MSECS:
        stateName = org.apache.beam.runners.core.metrics.ExecutionStateTracker.FINISH_STATE_NAME;
        break;
      default:
        throw new IllegalArgumentException(String.format("Unknown URN %s", executionStateUrn));
    }
    this.shortIds = shortIds;
    this.executionStateUrn = executionStateUrn;
    this.stateTracker = stateTracker;
  }

  /**
   * Register the runnable to process the specific pTransformId and track its execution time.
   *
   * @param pTransformId
   * @param pTransformUniqueName
   * @param runnable
   */
  public void register(
      String pTransformId, String pTransformUniqueName, ThrowingRunnable runnable) {
    SimpleMonitoringInfoBuilder miBuilder = new SimpleMonitoringInfoBuilder();
    miBuilder.setUrn(executionStateUrn);
    miBuilder.setType(MonitoringInfoConstants.TypeUrns.SUM_INT64_TYPE);

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass only Urns constants intended for execution state (e.g. Urns.PROCESS_BUNDLE_MSECS, Urns.FINISH_BUNDLE_MSECS) to this registry.
2. Use the correct registry (PTransformMetrics/counter registration path) for non-execution-state monitoring info URNs.
3. Check the Urns class in your Beam version for the exact constant names; update custom code after upgrades.

Example fix

// before
new PTransformFunctionRegistry(..., "process_user_counter", ...);
// after
new PTransformFunctionRegistry(..., org.apache.beam.model.jobmanagement.v1.MonitoringInfoUrns.Urns.PROCESS_BUNDLE_MSECS, ...);

if (!Urns.PROCESS_BUNDLE_MSECS.equals(urn) && !Urns.FINISH_BUNDLE_MSECS.equals(urn)) { throw new IllegalArgumentException("Unsupported execution-state URN: " + urn); }

try { new PTransformFunctionRegistry(..., urn, ...); } catch (IllegalArgumentException e) { LOG.error("Bad execution-state URN: {}", urn, e); throw e; }

When it happens

Trigger: Constructing PTransformFunctionRegistry with an executionStateUrn that is not PROCESS_BUNDLE_MSECS or FINISH_BUNDLE_MSECS (per the switch) — e.g. registering a user counter URN or a mistyped/renamed URN through this registry.

Common situations: Custom runners or tests registering execution-state metrics with an incorrect URN constant; SDK changes renaming/moving Urns constants so custom code passes an outdated value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unable to construct %s counter for PTransform {id=%s, name=%
• This runner does not currently support committed metrics res
• getMonitoringInfos is not implemented on this MetricsContain
• NoOpMetricsSink was not found on classpath
• Internal error initializing BeamFnDataReadRunner: invalid mo

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