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

Error message

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

What it means

startAutomatedJavaExpansionService downloads/prepares the expansion service jar (NewExpansionServiceRunner) before launching it. If constructing the runner fails — jar resolution, gradle target lookup, or local setup issues — this error wraps the cause along with the gradle target and classpath used.

Source

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

	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
		}
	}

	serviceRunner, err := expansionx.NewExpansionServiceRunner(jarPath, "")
	if err != nil {
		return nil, "", fmt.Errorf("error in  startAutomatedJavaExpansionService(%s,%s): %w", gradleTarget, classpath, 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
}

// QueryAutomatedExpansionService submits an external 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 QueryAutomatedExpansionService(ctx context.Context, p *HandlerParams) (*jobpb.ExpansionResponse, error) {

View on GitHub (pinned to 12126d8942)

Solutions

Check the wrapped error and the reported gradle target/classpath; verify the target coordinates are correct.
Ensure Java and Gradle are installed and reachable (JAVA_HOME, PATH).
Pre-download or cache the expansion service jar to avoid network resolution at runtime.
Use an external (pre-started) expansion service endpoint instead of automated expansion.
Check disk space/permissions in the directory where the jar is staged.

Example fix

// before
res, err := xlangx.QueryAutomatedExpansionService(ctx, req, nil, gradleTarget) // no Java env
// after
// point at a running service instead
res, err := xlangx.Expand(ctx, req, nil, "localhost:8097")

Defensive patterns

Strategy: fallback

Validate before calling

if _, err := exec.LookPath("java"); err != nil {
	return fmt.Errorf("automated expansion requires Java on PATH: %w", err)
}

Try / catch

stop, addr, err := xlangx.QueryAutomatedExpansionService(ctx, req, o, target)
if err != nil {
	return fmt.Errorf("automated expansion failed (%v); start a service manually and use xlangx.Expand", err)
}
defer stop()

Prevention

Install and verify Java/Gradle before using automated expansion.
Pre-fetch and cache the expansion jar for offline/CI environments.
Prefer a pre-started external expansion service in production.

When it happens

Trigger: Calling QueryAutomatedExpansionService which invokes startAutomatedJavaExpansionService when NewExpansionServiceRunner(jarPath, "") returns an error: missing jar, failed gradle resolution of the target, or invalid classpath/environment.

Common situations: No local Gradle/Java toolchain, offline environments where the jar cannot be fetched, wrong gradleCoordinates target for the transform, or filesystem permission issues when staging the jar.

Related errors

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