apache/beam · error · RuntimeException

Expansion request to transform service failed.

Error message

Expansion request to transform service failed.

What it means

Thrown by ExpansionService.processExpand after the client failed to obtain a successful expansion response from any configured transform service endpoint. All candidate expansion services either raised RuntimeExceptions or returned errors, so the last exception is rethrown with the generic message. The original cause is attached, so inspect getCause() for the real failure.

Source

Thrown at sdks/java/transform-service/src/main/java/org/apache/beam/sdk/transformservice/ExpansionService.java:198

    // Trying out expansion services in order till one succeeds.
    // If all services fail, re-raises the last error.
    Map<String, ExpansionResponse> errorResponses = new HashMap<>();
    RuntimeException lastException = null;
    for (Endpoints.ApiServiceDescriptor endpoint : endpoints) {
      try {
        ExpansionApi.ExpansionResponse response =
            expansionServiceClientFactory.getExpansionServiceClient(endpoint).expand(request);
        if (!response.getError().isEmpty()) {
          errorResponses.put(endpoint.getUrl(), response);
          continue;
        }
        return response;
      } catch (RuntimeException e) {
        lastException = e;
      }
    }
    if (lastException != null) {
      throw new RuntimeException("Expansion request to transform service failed.", lastException);
    }
    if (!errorResponses.isEmpty()) {
      return getAggregatedErrorResponse(errorResponses);
    } else if (lastException != null) {
      throw new RuntimeException("Expansion request to transform service failed.", lastException);
    } else {
      throw new RuntimeException("Could not process the expansion request: " + request);
    }
  }

  ExpansionApi.DiscoverSchemaTransformResponse processDiscover(
      ExpansionApi.DiscoverSchemaTransformRequest request) {
    // Trying out expansion services and aggregating all successful results.
    // If all services fail, return the last successful response any.
    // If there are no successful responses, re-raises the last error.
    List<ExpansionApi.DiscoverSchemaTransformResponse> successfulResponses = new ArrayList<>();
    ExpansionApi.DiscoverSchemaTransformResponse lastErrorResponse = null;
    for (Endpoints.ApiServiceDescriptor endpoint : endpoints) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the chained cause (e.getCause()) to find the actual failure from the expansion service call.
2. Verify the expansion service endpoint(s) in the Transform Service config YAML are reachable (host/port, no firewall block).
3. Ensure the transform service is started and healthy before submitting the pipeline.
4. Check that SDK and expansion service versions match.

Example fix

// before: opaque failure
throw new RuntimeException("Expansion request to transform service failed.", lastException);
// after: surface cause and check service availability first
if (lastException != null) {
  throw new RuntimeException(
      "Expansion request to transform service failed: " + lastException.getMessage(), lastException);
}

// before expansion, check endpoints are reachable
for (String ep : expansionServiceEndpoints) {
  String[] hp = ep.split(":");
  try (java.net.Socket s = new java.net.Socket(hp[0], Integer.parseInt(hp[1]))) {
    // reachable
  } catch (IOException e) {
    throw new IllegalStateException("Expansion service unreachable: " + ep, e);
  }
}

try {
  expansionResult = expansionService.expand(request);
} catch (RuntimeException e) {
  Throwable root = e;
  while (root.getCause() != null) root = root.getCause();
  LOG.error("Expansion failed; root cause: {}", root.getMessage(), root);
  throw new IllegalStateException("Transform service unreachable or failed; root cause: " + root.getMessage(), e);
}

When it happens

Trigger: Calling expansion (e.g. via pipeline.apply with an external transform resolved by a transform service) when every configured expansion service endpoint throws a RuntimeException during the request/receive cycle — e.g. service down, gRPC failure, or malformed response.

Common situations: Transform service container not running or unreachable; wrong expansion service address in the config; network/firewall blocking the gRPC port; service crashing mid-expansion; incompatible Beam SDK/service versions.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• expansion service error: %s
• Timeout waiting for Python service startup after ${elapsed}
• Could not process the expansion request: + request
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed

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