apache/beam · error

translation failed

Error message

translation failed

What it means

Once the graph builds, Execute compiles it into an executable plan via Compile(edges). Failures during translation (unsupported transform combination, missing coders, expansion failure of a unit) are wrapped as 'translation failed'. This sits between graph construction and actual execution.

Source

Thrown at sdks/go/pkg/beam/runners/direct/direct.go:69

	log.Info(ctx, "Pipeline:")
	log.Info(ctx, p)
	ctx = metrics.SetBundleID(ctx, "direct") // Ensure a metrics.Store exists.

	if *jobopts.Strict {
		log.Info(ctx, "Strict mode enabled, applying additional validation.")
		if _, err := vet.Execute(ctx, p); err != nil {
			return nil, errors.Wrap(err, "strictness check failed")
		}
		log.Info(ctx, "Strict mode validation passed.")
	}

	edges, _, err := p.Build()
	if err != nil {
		return nil, errors.Wrap(err, "invalid pipeline")
	}
	plan, err := Compile(edges)
	if err != nil {
		return nil, errors.Wrap(err, "translation failed")
	}
	beam.PipelineOptions.LoadOptionsFromFlags(nil)
	log.Info(ctx, plan)

	if err = plan.Execute(ctx, "", exec.DataContext{}); err != nil {
		plan.Down(ctx) // ignore any teardown errors
		return nil, err
	}
	if err = plan.Down(ctx); err != nil {
		return nil, err
	}

	return newDirectPipelineResult(ctx)
}

type directPipelineResult struct {
	jobID   string
	metrics *metrics.Results

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the inner error from Compile to see which edge/unit failed translation.
2. Check for unsupported features in the pipeline (custom windowing, external transforms, exotic coders) and simplify or switch runners.
3. Upgrade or align Apache Beam Go SDK versions so graph and runner packages match.
4. Reproduce with a minimal pipeline adding one transform at a time to isolate the offending construct.

Example fix

// before
w := window.NewCustomWindowing(myUnstableFn) // translator unsupported
out := beam.WindowInto(s, w, col)
// after
out := beam.WindowInto(s, window.NewFixedWindows(time.Minute), col)

if _, err := beam.Run(ctx, runner, p); err != nil && strings.Contains(err.Error(), "translation failed") {
    log.Printf("unsupported construct for direct runner, see inner error: %v", err)
}

When it happens

Trigger: beam.Run on the direct runner where Compile(edges) cannot translate a built edge graph — e.g. an unsupported windowing/coder combination or a transform whose translation unit cannot be constructed.

Common situations: Using unusual windowing strategies or custom coders not supported by the direct runner; cross-language transforms reaching translation; pipelines built by graph manipulation APIs with inconsistent metadata; version mismatches between beam core packages.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• strictness check failed
• invalid pipeline
• unexpected edge: %v
• could not detect user main
• external transforms like %v are not supported in the Go dire

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