apache/beam · error

expansion response error

Error message

expansion response error

What it means

Raised in xlangx.QueryExpansionService when the expansion service responds successfully at the gRPC level but its ExpansionResponse carries a non-empty Error string. The remote service itself reported a problem expanding the transform; the library wraps that message as "expansion response error". The underlying text names the actual remote failure.

Source

Thrown at sdks/go/pkg/beam/core/runtime/xlangx/expand.go:192

		retry.DelayType(func(n uint, err error, config *retry.Config) time.Duration {
			if n == 0 {
				return time.Second
			}
			return retry.BackOffDelay(n, err, config)
		}),
	}
	var res *jobpb.ExpansionResponse
	err = retry.Do(func() error {
		res, err = client.Expand(ctx, req)
		return err
	}, retryOpts...)
	if err != nil {
		err = errors.Wrap(err, "expansion failed")
		return nil, errors.WithContextf(err, "expanding transform with ExpansionRequest: %v", req)
	}
	if len(res.GetError()) != 0 { // ExpansionResponse includes an error.
		err := errors.New(res.GetError())
		err = errors.Wrap(err, "expansion response error")
		return nil, errors.WithContextf(err, "expanding transform with ExpansionRequest: %v", req)
	}

	return res, nil
}

func startAutomatedJavaExpansionService(gradleTarget string, classpath string) (stopFunc func() error, address string, err error) {
	jarPath, err := expansionx.GetBeamJar(gradleTarget, core.SdkVersion)
	if err != nil {
		return nil, "", err
	}

	if len(classpath) > 0 {
		jarPath, err = expansionx.MakeJar(jarPath, classpath)
		if err != nil {
			return nil, "", err
		}
	}

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the wrapped res.GetError() text — it states the remote cause
2. Verify the requested transform URN exists in the expansion service's environment (installed package/JAR)
3. Ensure expansion service artifacts (JAR/Beam package) match the pipeline's Beam version
4. Fix remote-side configuration (classpath, dependencies, transform payload) reported by the service

Example fix

// before
beam.CrossLanguage(s, "my.org:missing:transform:v1", cfg, nil, in) // URN not in service
// after
beam.CrossLanguage(s, "my.org:existing:transform:v1", cfg, nil, in)

// check the transform URN is implemented by the service before expansion
if !serviceSupportsURN(urn) {
    return fmt.Errorf("transform %q not available in expansion service", urn)
}

res, err := xlangx.QueryExpansionService(ctx, params)
if err != nil {
    // the remote cause is embedded; surface it to the user
    return fmt.Errorf("expansion rejected by service: %w", err)
}

When it happens

Trigger: Any QueryPythonExpansionService/QueryAutomatedExpansionService call where the remote expansion service rejects the ExpansionRequest: missing transform URN on the service side, incompatible payload, construction failure of the remote transform.

Common situations: Requesting a Java/Python transform that does not exist in the expansion service's classpath/installed packages; constructor or validation errors in the remote transform; version mismatch between SDK and the expansion service artifacts.

Related errors

• expansion service error: %s
• Could not find coder for URN " + urn
• ${response.error}
• Unable to instantiate ExternalTransformBuilder from construc
• expansion service error: %s

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