error in startAutomatedPythonExpansionService(%s,%s): %w

Error message

error in  startAutomatedPythonExpansionService(%s,%s): %w

What it means

This error is returned by startPythonExpansionService when expansionx.NewPyExpansionServiceRunner fails to construct a runner object that would launch an automated Python expansion service subprocess. The library wraps the underlying cause (typically a failed exec.LookPath or bad argument combination) so callers know the failure occurred during runner creation, not service startup. The %s,%s arguments log the venv Python binary path and the service module spec that were passed in.

Source

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

	}

	// Restore tag so we know the artifacts have been materialized eagerly down the road.
	p.edge.External.ExpansionAddr = tag + Separator + target

	// Can return the original response because all of our proto modification afterwards has
	// been via pointer.
	return res, nil
}

func startPythonExpansionService(service, extraPackage string) (stopFunc func() error, address string, err error) {
	venvPython, err := expansionx.SetUpPythonEnvironment(extraPackage)
	if err != nil {
		return nil, "", err
	}

	serviceRunner, err := expansionx.NewPyExpansionServiceRunner(venvPython, service, "")
	if err != nil {
		return nil, "", fmt.Errorf("error in  startAutomatedPythonExpansionService(%s,%s): %w", venvPython, service, err)
	}
	err = serviceRunner.StartService()
	if err != nil {
		return nil, "", fmt.Errorf("error in starting expansion service, StartService(): %w", err)
	}
	stopFunc = serviceRunner.StopService
	address = serviceRunner.Endpoint()
	return stopFunc, address, nil
}

// QueryPythonExpansionService submits an external python transform to be expanded by the
// expansion service and then eagerly materializes the artifacts for staging. The given
// transform should be the external transform, and the components are any additional
// components necessary for the pipeline snippet.
//
// The address to be queried is determined by the Config field of the HandlerParams after
// the prefix tag indicating the automated service is in use.
func QueryPythonExpansionService(ctx context.Context, p *HandlerParams) (*jobpb.ExpansionResponse, error) {

View on GitHub (pinned to 12126d8942)

Solutions

Verify the venvPython path exists and is executable (run `<venvPython> --version` manually).
Check the service argument matches the expected module spec (e.g. apache_beam.runners.portability.expansion_service_main) for the installed Beam Python version.
Inspect the wrapped cause (%w) in the error chain for the real underlying failure.
Recreate the Python virtualenv and reinstall apache_beam to restore the expansion service entry point.

Example fix

// before
stopFunc, addr, err := xlangx.QueryPythonExpansionService(ctx, "venv", "python3", service)
// after
if _, err := os.Stat(venvPython); err != nil {
    return fmt.Errorf("venv python missing at %s: %w", venvPython, err)
}
stopFunc, addr, err := xlangx.QueryPythonExpansionService(ctx, venvPython, service)

Defensive patterns

Strategy: validation

Validate before calling

if fi, err := os.Stat(venvPython); err != nil || fi.IsDir() {
    return fmt.Errorf("venv python not usable at %s: %v", venvPython, err)
}
if out, err := exec.Command(venvPython, "--version").CombinedOutput(); err != nil {
    return fmt.Errorf("venv python not runnable: %v: %s", err, out)
}

Try / catch

if stopFunc, addr, err := xlangx.QueryPythonExpansionService(ctx, venvPython, service); err != nil {
    var inner error
    if errors.Unwrap(err) != nil { inner = errors.Unwrap(err) }
    log.Printf("expansion runner init failed: %v (cause: %v)", err, inner)
    return err
}

Prevention

Verify the venv python binary exists and executes before starting cross-language pipelines.
Pin apache_beam version in the venv to match the Beam Go SDK version.
Log venvPython and service args in pipeline setup for debuggability.

When it happens

Trigger: QueryPythonExpansionService -> startPythonExpansionService with a venvPython path that does not exist or is not executable, or a service spec string NewPyExpansionServiceRunner rejects.

Common situations: A virtualenv was deleted or moved after being configured; BEAM Python SDK path misconfigured; passing a fully-qualified expansion service address when the runner expects a module name; Go worker running in a container without the Python venv installed.

Related errors

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