apache/beam · error · Error

${response.error}

Error message

${response.error}

What it means

In External expandInternalAsync(), the SDK calls the remote expansion service (client.expand). If the service's response contains an error field, the SDK surfaces it verbatim by throwing new Error(response.error). This propagates the expansion service's own failure message to the caller.

Source

Thrown at sdks/typescript/src/apache_beam/transforms/external.ts:188

      request.components!.environments,
      pipelineComponents.environments,
    );

    const service = await this.serviceProvider();
    const address = await service.start();

    const client = new ExpansionServiceClient(
      new GrpcTransport({
        host: address,
        channelCredentials: ChannelCredentials.createInsecure(),
      }),
    );

    try {
      const response = await client.expand(request).response;

      if (response.error) {
        throw new Error(response.error);
      }

      response.components = await this.resolveArtifacts(
        response.components!,
        address,
      );

      return this.splice(pipeline, transformProto, response, namespace);
    } finally {
      await service.stop();
    }
  }

  /**
   * The returned pipeline fragment may have dependencies (referenced in its)
   * environments) that are needed for execution. This function fetches (as
   * required) these artifacts from the expansion service (which may be
   * be transient) and stores them in files such that it may then forward

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the propagated response.error text — it names the remote expansion failure (often unknown URN or constructor exception).
2. Verify the external transform's URN and payload are supported by the expansion service version you run.
3. Ensure the expansion service and client Beam versions are compatible, and that the address points to the correct service.

Example fix

// before
await external.expandInternalAsync(...); // throws remote error
// after
try { await external.expandInternalAsync(...); }
catch (e) { console.error("Expansion service error:", e.message); throw e; }

// Verify the expansion service is reachable and supports the URN
const health = await fetch(`http://${address}/`); // simple reachability probe before expand

function hasError(r: { error?: string }): r is { error: string } { return typeof r.error === "string" && r.error.length > 0; }

try {
  await external.expandInternalAsync(...);
} catch (e) {
  console.error("Expansion service reported:", e.message); // message is the remote error
  throw e;
}

When it happens

Trigger: Expanding an external transform (cross-language) whose expansion service returns an error field — e.g. the remote SDK failed to construct the transform, the URN is unknown to the service, or the payload is invalid.

Common situations: Mismatched Beam versions between client and expansion service, unknown transform URN, wrong expansion service address/port pointing at the wrong service, or the remote SDK throwing during transform construction.

Related errors

• Could not find coder for URN " + urn
• Ambiguous renaming of tags.
• Unable to instantiate ExternalTransformBuilder from construc
• expansion service error: %s
• Received unknown SQL Dialect '%s'. Known dialects: %s

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