apache/beam · error

could not unmarshal global window coder: %w

Error message

could not unmarshal global window coder: %w

What it means

When decoding a global-window coder reference, makeCoder re-derives the window coder via b.WindowCoder(id) and failed; the underlying decode error is wrapped with this message. It means the global window reference cannot be resolved in the current components context.

Source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/coder.go:403

			return nil, errors.Errorf("could not unmarshal sharded_key coder from %v, expected one component (key) but got %d", c, len(components))
		}
		keyC, err := b.Coder(components[0])
		if err != nil {
			return nil, err
		}
		return coder.NewSK(keyC), nil
	case urnIntervalWindow:
		return coder.NewIntervalWindowCoder(), nil

	// Special handling for the global window coder so it can be treated as
	// a general coder. Generally window coders are not used outside of
	// specific contexts, but this enables improved testing.
	// Window types are not permitted to be fulltypes, so
	// we use assignably equivalent anonymous struct types.
	case urnGlobalWindow:
		w, err := b.WindowCoder(id)
		if err != nil {
			return nil, errors.Errorf("could not unmarshal global window coder: %w", err)
		}
		return &coder.Coder{Kind: coder.Window, T: typex.New(reflect.TypeOf((*struct{})(nil)).Elem()), Window: w}, nil
	default:
		return nil, errors.Errorf("could not unmarshal coder from %v, unknown URN %v", c, urn)
	}
}

func (b *CoderUnmarshaller) peek(id string) (*pipepb.Coder, error) {
	c, ok := b.models[id]
	if !ok {
		return nil, errors.Errorf("(peek) coder with id %v not found", id)
	}
	return c, nil
}

func (b *CoderUnmarshaller) isCoGBKList(id string) ([]string, bool) {
	elm, err := b.peek(id)
	if err != nil {

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the wrapped cause for why b.WindowCoder(id) failed (missing ID, bad payload)
2. Regenerate the pipeline graph with the Go SDK
3. Verify the coder's component references point to valid window coder entries
4. Align SDK versions between producer and harness

Example fix

// before: global window coder referencing a dropped component ID
// after: re-export the pipeline so the window coder component is present, e.g. {"urn":"beam:coder:global_window:v1","components":[]}

// ensure the window coder ID resolves in the components table before decoding
if _, err := b.WindowCoder(ref.ID); err != nil {
    return fmt.Errorf("window coder %q unresolvable: %w", ref.ID, err)
}

c, err := graphx.Coder(model, ref)
if err != nil {
    if strings.Contains(err.Error(), "global window coder") {
        return fmt.Errorf("window components missing from pipeline model: %w", err)
    }
    return err
}

When it happens

Trigger: Decoding beam:coder:global_window:v1 where the window lookup by ID fails — missing or invalid window component reference in the coder components map.

Common situations: Corrupted or hand-edited pipeline components; SDK version skew; window coder IDs referencing entries dropped during graph transformation.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• unwindowed coder %v on DataSource %v: %v
• could not unmarshal window coder for pcollection %v: %w
• unwindowed coder %v on DataSink %v: %v
• could not unmarshal window coder for timer: %w
• window must not be nil

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