apache/beam · error · Error

Unknown context parameter: ${param.parDoParamName}

Error message

Unknown context parameter: ${param.parDoParamName}

What it means

In the Beam TypeScript worker, PardoContext.lookup(param) resolves a DoFn parameter (Element, Timestamp, PaneInfo, SideInput, etc.) via a switch on param.parDoParamName. If the parameter name is not one of the handled cases, the worker throws this Error because it cannot supply a value for an unrecognized DoFn parameter.

Source

Thrown at sdks/typescript/src/apache_beam/worker/pardo_context.ts:177

      );
    }

    switch (param.parDoParamName) {
      case "window":
        // If we're here and there was more than one window, we have exploded.
        return this.wvalue.windows[0];

      case "timestamp":
        return this.wvalue.timestamp;

      case "paneinfo":
        return this.wvalue.pane;

      case "sideInput":
        return this.sideInputValues.get(param.sideInputId) as any;

      default:
        throw new Error("Unknown context parameter: " + param.parDoParamName);
    }
  }

  update(param, value) {
    switch (param.parDoParamName) {
      case "metric":
        this.metricsContainer
          .getMetric(this.transformId, undefined, param as MetricSpec)
          .update(value);
        break;

      default:
        throw new Error("Unknown context parameter: " + param.parDoParamName);
    }
  }
}

export interface SideInputInfo {

View on GitHub (pinned to 12126d8942)

Solutions

Upgrade the apache-beam TypeScript worker package to a version matching the SDK that built the pipeline, so the parameter name is recognized.
Inspect the failing pipeline graph's ParDo payload to see which parDoParamName is sent and confirm it is a standard Beam parameter.
Add the missing case to lookup() in pardo_context.ts if you maintain a fork and know how to resolve the new parameter.
File/report an issue to Beam with the parameter URN/name if it comes from a supported SDK version.

Example fix

// before (worker build predates new param)
// throws: Unknown context parameter: TIMER_TIMESTAMP
// after: upgrade @apache-beam/worker to a version that handles timer params, or pin SDK to compatible version

Defensive patterns

Strategy: try-catch

Validate before calling

// before submitting, confirm worker version matches SDK
if (param.parDoParamName && !['element','timestamp','window','paneinfo','sideInput','metric'].includes(param.parDoParamName)) {
  throw new Error(`Precheck: unsupported parDoParamName ${param.parDoParamName}`);
}

Type guard

const isKnownParam = (p: any): p is {parDoParamName: 'element'|'timestamp'|'paneinfo'|'sideInput'} =>
  ['element','timestamp','paneinfo','sideInput'].includes(p?.parDoParamName);

Try / catch

try {
  const v = ctx.lookup(param);
} catch (e) {
  if (String(e.message).startsWith('Unknown context parameter')) {
    // fail the instruction with a clear upgrade hint
    throw new Error(`Worker too old for param ${param.parDoParamName}; upgrade worker`);
  }
  throw e;
}

Prevention

Keep the TS worker package version aligned with the SDK that builds pipelines
Pin Beam SDK versions in your runner images
Smoke-test pipelines with new DoFn features on a staging runner before production

When it happens

Trigger: A ParDo instruction references a parDoParamName not in {element, timestamp, paneinfo/window, sideInput, ...} — e.g. a new Beam Fn API parameter type introduced in a newer runner/SDK version that this TypeScript worker build does not know, or a corrupted/older pipeline proto.

Common situations: Version mismatch between the runner (e.g. Python/Java pipeline submitting a job using a newly added context parameter) and an outdated TypeScript worker; custom pipeline graph manipulation producing an exotic ParDoPayload param.

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

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