apache/beam · error · Error

Unable to deduce name, please use withName(...).

Error message

Unable to deduce name, please use withName(...).

What it means

When a PTransform is created without an explicit name, extractName derives one by stringifying the transform's function/DoFn source code and normalizing whitespace. If the stringified source is 60 characters or longer, the name would be unwieldy, so the SDK throws and asks the developer to name the transform explicitly. This is a build-time convenience guard, not a runtime data error.

Solutions

1. Call .withName("MyStepName") on the transform.
2. Pass a short, named function instead of a long anonymous one.
3. Extract the logic into a named DoFn class so the class name is used.
4. Shorten the inline function so its source is under 60 characters.

Example fix

// before
pcoll.map((x) => { const a = doLongThing(x); return alsoDo(a, more(x)); });

// after
pcoll.map(enrich).withName("EnrichRecords");

function hasShortSource(fn: Function) { return fn.toString().replace(/\s+/gm, ' ').trim().length < 60; }

try {
  pcoll.map(longInlineFn);
} catch (e) {
  if (/Unable to deduce name/.test(String(e))) pcoll.map(longInlineFn).withName('Enrich');
  else throw e;
}

When it happens

Trigger: Using map/flatMap/filter/combining with an anonymous multi-line or long function without calling .withName(...) or passing a name.

Common situations: Inline arrow functions with long bodies used directly in map/flatMap; minified/bundled code where function.toString() yields long text; developers unaware names are auto-derived.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• buildDescriptor: invalid stage - no transforms at all
• can't get data to generate
• can't get data to render
• computeFacts: two producers for one PCollection
• Could not find subtransform to copy:

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

Appendix: source

Thrown at sdks/typescript/src/apache_beam/transforms/transform.ts:66

  if (untyped.beamName !== null && untyped.beamName !== undefined) {
    if (typeof untyped.beamName === "string") {
      return untyped.beamName;
    } else {
      return untyped.beamName();
    }
  } else if (untyped.name && untyped.name !== "anonymous") {
    return untyped.name;
  } else {
    const stringified = ("" + withName)
      // Remove injected code coverage boilerplate.
      .replace(/__cov_.*?[+][+]/g, " ")
      // Normalize whitespace.
      .replace(/\s+/gm, " ")
      .trim();
    if (stringified.length < 60) {
      return stringified;
    } else {
      throw new Error("Unable to deduce name, please use withName(...).");
    }
  }
}

// NOTE: It could be more idiomatic javascript to simply use the function type
// (InputT, Pipeline, runnerApi.PTransform) => OutputT rather than a transform
// class hierarchy here, a class is chosen to serve as a more obvious
// representative for other languages to follow.
// This more functional form is still preferred for users, and accepted
// as an argument to apply for the various pvalues (see pvalue.ts).
//
// Note also that the requirement for both a synchronous and asynchronous
// variant is imposed by javascript, and is not necessarily relevant in other
// languages (especially if an asynchronous call can be turned into a blocking
// call rather than forcing the asynchronous nature all the way up the call
// hierarchy).

/** @internal */

View on GitHub (pinned to 12126d8942)