What causes "failed to serialize %v" in apache/beam?

Inspect the wrapped cause (errors.Wrapf preserves it) for the real serialization failure.

failed to serialize

Error message

failed to serialize %v

What it means

mustEncodeMultiEdgeBase64 wraps any failure from EncodeMultiEdge (serializing a transform/MultiEdge into a proto ref) with this message. It indicates the DoFn or transform payload could not be serialized during pipeline graph encoding.

Solutions

Inspect the wrapped cause (errors.Wrapf preserves it) for the real serialization failure.
Verify the DoFn conforms to beam.DoFn requirements (ProcessElement signature, exportable fields).
Remove or replace custom coders/side inputs that fail to serialize, and rebuild the pipeline with a supported transform.

Defensive patterns

Strategy: try-catch

Try / catch

ref, err := graphx.EncodeMultiEdge(edge)
if err != nil {
    return fmt.Errorf("transform %v not serializable: %w", edge, err)
}

Prevention

Keep DoFn structs simple and free of unserializable fields (channels, funcs, open handles).
Test pipeline construction locally with a direct runner before submitting.
Read the wrapped cause first; graphx errors nest the real failure.

When it happens

Trigger: EncodeMultiEdge returns an error (e.g. a DoFn with unsupported parameters, unserializable side input/state, or an invalid graph edge) while encoding a multi-edge for the runner payload.

Common situations: Using a DoFn whose signature or fields are not serializable; passing unsupported side inputs or custom coders; graph construction bugs from misuse of the beam scope API.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/translate.go:1483

		return nil, errors.Errorf("unexpected windowing strategy: %v", w)
	}
}

func makeWindowCoder(w *window.Fn) (*coder.WindowCoder, error) {
	switch w.Kind {
	case window.GlobalWindows:
		return coder.NewGlobalWindow(), nil
	case window.FixedWindows, window.SlidingWindows, window.Sessions, URNSlidingWindowsWindowFn:
		return coder.NewIntervalWindow(), nil
	default:
		return nil, errors.Errorf("unexpected windowing strategy for coder: %v", w)
	}
}

func mustEncodeMultiEdgeBase64(edge *graph.MultiEdge) (string, error) {
	ref, err := EncodeMultiEdge(edge)
	if err != nil {
		return "", errors.Wrapf(err, "failed to serialize %v", edge)
	}
	return protox.MustEncodeBase64(&v1pb.TransformPayload{
		Urn:  URNDoFn,
		Edge: ref,
	}), nil
}

func edgeID(edge *graph.MultiEdge) string {
	return fmt.Sprintf("e%v", edge.ID())
}

func nodeID(n *graph.Node) string {
	return fmt.Sprintf("n%v", n.ID())
}

func scopeID(s *graph.Scope) string {
	return fmt.Sprintf("s%v", s.ID())
}

View on GitHub (pinned to 12126d8942)