apache/beam · error

unknown urn to Prepare:

Error message

unknown urn to Prepare: 

What it means

PrepareTransform dispatches on the transform's spec URN to a dedicated handler (ParDo, GBK, Flatten, Reshuffle, TestStream, etc.). When the URN does not match any known case, the runner panics because it has no strategy for that transform. This is a hard internal limitation of the prism runner's supported transform set.

Solutions

1. Check the transform URN in the pipeline dump and confirm it is in prism's supported set (ParDo, GBK, Flatten, Reshuffle, TestStream, and composites).
2. Align SDK and prism to the same Beam version so both sides know the same URNs.
3. Refactor the pipeline to avoid the unsupported transform (e.g. replace a custom URN with standard beam transforms).
4. If the URN should be supported, report it upstream to the Beam project.

known := map[string]bool{urns.TransformParDo:true, urns.TransformGBK:true, urns.TransformFlatten:true, urns.TransformReshuffle:true, urns.TransformTestStream:true}
if !known[t.GetSpec().GetUrn()] { /* unsupported transform for prism */ }

defer func(){ if r := recover(); r != nil && strings.Contains(fmt.Sprint(r), "unknown urn to Prepare") { /* report unsupported transform */ } }()

When it happens

Trigger: Submitting a pipeline containing a transform URN prism does not implement, e.g. a runner-native PTransform URN introduced in a newer SDK, a custom transform URN, or an exotic composite that survives pipeline simplification.

Common situations: Cross-language (xlang) pipelines whose external transforms use URNs prism hasn't implemented; SDK and prism from different Beam versions where the SDK emits a newer URN; custom expansion results from a schema-aware or external transform service.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Expected single input PCollection in reshuffle:
• Expected single output PCollection in reshuffle:
• panic(err) propagating lpUnknownCoders error
• SDK side reshuffle not yet supported
• AfterProcessingTime trigger set without a delay or…

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

Appendix: source

Thrown at sdks/go/pkg/beam/runners/prism/internal/handlerunner.go:90

		urns.TransformReshuffle,
		urns.TransformRedistributeArbitrarily,
		urns.TransformRedistributeByKey,
		urns.TransformFlatten,
		urns.TransformTestStream,
	}
}

// PrepareTransform handles special processing with respect runner transforms, like reshuffle.
func (h *runner) PrepareTransform(tid string, t *pipepb.PTransform, comps *pipepb.Components) prepareResult {
	switch t.GetSpec().GetUrn() {
	case urns.TransformFlatten:
		return h.handleFlatten(tid, t, comps)
	case urns.TransformReshuffle, urns.TransformRedistributeArbitrarily, urns.TransformRedistributeByKey:
		return h.handleReshuffle(tid, t, comps)
	case urns.TransformTestStream:
		return h.handleTestStream(tid, t, comps)
	default:
		panic("unknown urn to Prepare: " + t.GetSpec().GetUrn())
	}
}

func (h *runner) handleFlatten(tid string, t *pipepb.PTransform, comps *pipepb.Components) prepareResult {
	if !h.config.SDKFlatten && !strings.HasPrefix(tid, "ft_") {
		forcedRoots := []string{tid} // Have runner side transforms be roots.

		// Force runner flatten consumers to be roots.
		// This resolves merges between two runner transforms trying
		// to execute together.
		outColID := getOnlyValue(t.GetOutputs())
		for ctid, t := range comps.GetTransforms() {
			for _, gi := range t.GetInputs() {
				if gi == outColID {
					forcedRoots = append(forcedRoots, ctid)
				}
			}
		}

View on GitHub (pinned to 12126d8942)