apache/beam · error

prism error building stage %v: %w

Error message

prism error building stage %v: 
%w

What it means

This error wraps a failure from buildDescriptor when executePipeline processes a worker-environment (wk.Env) element of the pipeline. buildDescriptor assembles the bundle descriptor / environment configuration for the stage; any error it returns (missing environment config, bad coders, failed container setup data) is wrapped with the stage ID and the underlying cause via %w. It is the prism runner's stage-construction failure point for environment-backed transforms.

Source

Thrown at sdks/go/pkg/beam/runners/prism/internal/execute.go:323

							tsb.AddProcessingTimeEvent(time.Duration(mtime.MaxTimestamp))
						} else {
							tsb.AddProcessingTimeEvent(time.Duration(ev.ProcessingTimeEvent.GetAdvanceDuration()) * time.Millisecond)
						}

					default:
						return fmt.Errorf("prism error building stage %v - unknown TestStream event type: %T", stage.ID, ev)
					}
				}

			case urns.TransformFlatten:
				inputs := maps.Values(t.GetInputs())
				sort.Strings(inputs)
				em.AddStage(stage.ID, inputs, []string{getOnlyValue(t.GetOutputs())}, nil)
			}
			stages[stage.ID] = stage
		case wk.Env:
			if err := buildDescriptor(stage, comps, wk, em); err != nil {
				return fmt.Errorf("prism error building stage %v: \n%w", stage.ID, err)
			}
			stages[stage.ID] = stage
			outputs := maps.Keys(stage.OutputsToCoders)
			sort.Strings(outputs)
			em.AddStage(stage.ID, []string{stage.primaryInput}, outputs, stage.sideInputs)
			if stage.stateful {
				em.StageStateful(stage.ID, stage.stateTypeLen)
			}
			if stage.onWindowExpiration.TimerFamily != "" {
				slog.Debug("OnWindowExpiration", slog.String("stage", stage.ID), slog.Any("values", stage.onWindowExpiration))
				em.StageOnWindowExpiration(stage.ID, stage.onWindowExpiration)
			}
			if len(stage.processingTimeTimers) > 0 {
				em.StageProcessingTimeTimers(stage.ID, stage.processingTimeTimers)
			}
			stage.sdfSplittable = config.EnableSDFSplit
		default:
			return fmt.Errorf("unknown environment[%v]", t.GetEnvironmentId())

View on GitHub (pinned to 12126d8942)

Solutions

  1. Read the wrapped (%w) inner error in the message — it names the concrete buildDescriptor failure.
  2. Verify the environment config referenced by the stage is valid and complete in the submitted pipeline proto.
  3. Ensure SDK harness/container images and prism runner versions are compatible.
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate environment configs exist in the pipeline proto before submission
for id, env := range comps.GetEnvironments() {
    if env.GetUrn() == "" { log.Fatalf("environment %q has empty URN", id) }
}

Try / catch

if err := beamx.Run(ctx, p); err != nil {
    if strings.Contains(err.Error(), "prism error building stage") {
        log.Fatalf("stage build failed: %+v", err) // unwrap %w chain with errors.Unwrap
    }
    return err
}

Prevention

When it happens

Trigger: Calling RunPipeline on a pipeline whose stages include an environment (Docker/external/loopback) transform, and buildDescriptor fails — e.g. the referenced environment config is missing or malformed, or the stage's coders/descriptors cannot be built.

Common situations: Cross-language pipelines whose environment config was not provisioned; malformed pipeline protobufs; SDK/proto version mismatches leaving the environment definition incomplete in the model.

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

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