apache/beam · error

failed to cross-compile

Error message

failed to cross-compile %v, see https://beam.apache.org/documentation/sdks/go-cross-compilation/ for details: %v
%v

What it means

The universal runner builds (cross-compiles) a Go worker binary on the fly when submitting a pipeline to a remote runner. If the `go build` command fails — for the target GOOS/GOARCH or with the container environment settings — the runner wraps the command error and combined output in this error, pointing at the cross-compilation docs.

Solutions

1. Read the trailing build output in the error message to find the actual compile failure and fix that code error.
2. If cgo is the issue, ensure the worker code has no cgo dependencies or adjust CGO_ENABLED in the environment.
3. Install/verify a matching Go toolchain version on the machine submitting the job.
4. Use a pre-built worker binary and submit it explicitly (process/container environment) to skip cross-compilation.

Example fix

// before: cgo package breaks cross-compile
//   CGO_ENABLED=1 with GOOS=linux while building on darwin
// after: keep the build pure-Go
//   set environment CGO_ENABLED=0 or remove the cgo-importing dependency

// shell: verify the worker compiles for the target platform before submitting
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath ./my/worker/package

if err := beam.Run(ctx, runner, p); err != nil && strings.Contains(err.Error(), "failed to cross-compile") {
    // inspect build output appended to the error and fix the compile error
}

When it happens

Trigger: buildWorkerBinary runs `go build` with GOOS/GOARCH (and optionally CGO_ENABLED / container env) set for a different platform than the local one, and the build fails; called via BuildTempWorkerBinary during job submission.

Common situations: Cross-compiling a pipeline that imports cgo-dependent packages; missing Go toolchain on the submission machine; worker package fails to compile due to code errors; unsupported GOOS/GOARCH combination.

Related errors

• bad coder kind
• bad CoGBK
• bad combinefn
• bad decode
• bad decoding function

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

Appendix: source

Thrown at sdks/go/pkg/beam/runners/universal/runnerlib/compile.go:113

	cgo := "0"

	log.Infof(ctx, "Cross-compiling %v with GOOS=%s GOARCH=%s CGO_ENABLED=%s as %v", program, goos, goarch, cgo, filename)

	// Cross-compile given go program. Not awesome.
	program = program[:strings.LastIndex(program, "/")+1]
	program = program + "."
	var build []string
	if isTest {
		build = []string{"go", "test", "-trimpath", "-c", "-o", filename, program}
	} else {
		build = []string{"go", "build", "-trimpath", "-o", filename, program}
	}

	cmd := exec.Command(build[0], build[1:]...)
	cmd.Env = append(os.Environ(), "GOOS="+goos, "GOARCH="+goarch, "CGO_ENABLED="+cgo)
	if out, err := cmd.CombinedOutput(); err != nil {
		return errors.Errorf("failed to cross-compile %v, see https://beam.apache.org/documentation/sdks/go-cross-compilation/ for details: %v\n%v", program, err, string(out))
	}
	return nil
}

View on GitHub (pinned to 12126d8942)