apache/beam · error

while executing StartBundle for

Error message

while executing StartBundle for %v

What it means

During bundle processing, Plan.Execute calls StartBundle on each root unit; if any root fails, the plan is marked Broken and this wrapped error is returned. The underlying cause is typically the ParDo.StartBundle status error (5001) or a DoFn StartBundle hook failure.

Solutions

1. Unwrap the returned error to identify the failing root unit and its actual failure cause.
2. Fix the DoFn StartBundle hook: it must succeed for every bundle; verify any external clients/config it initializes.
3. Rebuild the plan after the failure - Broken plans cannot process further bundles.

Example fix

// before
if err := plan.Execute(ctx, id, mgr); err != nil { return err }
// after
if err := plan.Execute(ctx, id, mgr); err != nil {
    if strings.Contains(err.Error(), "StartBundle") {
        log.Printf("bundle start failed: %v", err) // inspect DoFn StartBundle hook
    }
    return err
}

if err := plan.Execute(ctx, id, mgr); err != nil {
    if strings.Contains(err.Error(), "StartBundle") {
        log.Printf("DoFn StartBundle hook failed: %v", err) // unwrap for root cause
    }
    return err
}

When it happens

Trigger: A root unit's StartBundle returning an error: DoFn @StartBundle callback panics or fails, status is not Up, or the DataContext provides invalid reader/timer state.

Common situations: DoFn StartBundle hooks with side effects failing (bad client init, missing config); executing a bundle on a plan whose Up failed silently in a prior step; test harnesses supplying nil DataContext fields.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• while executing Up for
• AfterProcessingTime trigger set without a delay or…
• array len mismatch. decoding
• At least one subtrigger required for composite triggers.
• attempted to add namespace to missing coder id

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/exec/plan.go:146

			}
		}
		p.setStatus(Up)
	}
	if p.source != nil {
		p.source.InitSplittable()
	}

	if s := p.getStatus(); s != Up {
		return errors.Errorf("invalid status for plan %v: %v", p.id, s)
	}

	// Process bundle. If there are any kinds of failures, we bail and mark the plan broken.

	p.setStatus(Active)
	for _, root := range p.roots {
		if err := callNoPanic(ctx, func(ctx context.Context) error { return root.StartBundle(ctx, id, manager) }); err != nil {
			p.setStatus(Broken)
			return errors.Wrapf(err, "while executing StartBundle for %v", p)
		}
	}
	for _, root := range p.roots {
		if err := callNoPanic(ctx, func(ctx context.Context) error {
			cps, err := root.Process(ctx)
			p.checkpoints = cps
			return err
		}); err != nil {
			p.setStatus(Broken)
			return errors.Wrapf(err, "while executing Process for %v", p)
		}
	}
	for _, root := range p.roots {
		if err := callNoPanic(ctx, root.FinishBundle); err != nil {
			p.setStatus(Broken)
			return errors.Wrapf(err, "while executing FinishBundle for %v", p)
		}
	}

View on GitHub (pinned to 12126d8942)