{"record":{"id":"bedb3db5d8b534b2","repo":"apache/beam","slug":"response-error","errorCode":null,"errorMessage":"${response.error}","messagePattern":"\\$\\{response\\.error\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"sdks/typescript/src/apache_beam/transforms/external.ts","lineNumber":188,"sourceCode":"      request.components!.environments,\n      pipelineComponents.environments,\n    );\n\n    const service = await this.serviceProvider();\n    const address = await service.start();\n\n    const client = new ExpansionServiceClient(\n      new GrpcTransport({\n        host: address,\n        channelCredentials: ChannelCredentials.createInsecure(),\n      }),\n    );\n\n    try {\n      const response = await client.expand(request).response;\n\n      if (response.error) {\n        throw new Error(response.error);\n      }\n\n      response.components = await this.resolveArtifacts(\n        response.components!,\n        address,\n      );\n\n      return this.splice(pipeline, transformProto, response, namespace);\n    } finally {\n      await service.stop();\n    }\n  }\n\n  /**\n   * The returned pipeline fragment may have dependencies (referenced in its)\n   * environments) that are needed for execution. This function fetches (as\n   * required) these artifacts from the expansion service (which may be\n   * be transient) and stores them in files such that it may then forward","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/typescript/src/apache_beam/transforms/external.ts#L170-L206","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the propagated response.error text — it names the remote expansion failure (often unknown URN or constructor exception).","Verify the external transform's URN and payload are supported by the expansion service version you run.","Ensure the expansion service and client Beam versions are compatible, and that the address points to the correct service."],"exampleFix":"// before\nawait external.expandInternalAsync(...); // throws remote error\n// after\ntry { await external.expandInternalAsync(...); }\ncatch (e) { console.error(\"Expansion service error:\", e.message); throw e; }","handlingStrategy":"try-catch","validationCode":"// Verify the expansion service is reachable and supports the URN\nconst health = await fetch(`http://${address}/`); // simple reachability probe before expand","typeGuard":"function hasError(r: { error?: string }): r is { error: string } { return typeof r.error === \"string\" && r.error.length > 0; }","tryCatchPattern":"try {\n  await external.expandInternalAsync(...);\n} catch (e) {\n  console.error(\"Expansion service reported:\", e.message); // message is the remote error\n  throw e;\n}","preventionTips":["Match Beam versions between client and expansion service","Verify the transform URN is registered in the remote SDK","Confirm the expansion service address/port is correct","Check expansion service startup logs for construction errors"],"tags":["external-transform","expansion-service","cross-language"],"backgroundTag":"api-error-response","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}