What causes "len mismatch decoding a %v: want %d got %d" in apache/beam?

Ensure writer and reader agree on the exact array type and length

len mismatch decoding a %v: want %d got %d

Error message

len mismatch decoding a %v: want %d got %d

What it means

When decoding an array-typed iterable, the decoder reads an int32 size from the stream and compares it with the fixed length rt.Len() of the target array type; on mismatch it errors with "len mismatch decoding a %v: want %d got %d". The Beam array iterable protocol requires the declared element count to exactly equal the static array length.

Source

Thrown at sdks/go/pkg/beam/core/graph/coder/iterable.go:140

		default:
			return errors.Errorf("unable to decode slice iterable with size: %d", n)
		}
	}
}

// iterableDecoderForArray can decode from only the fixed sized and
// multi-chunk variant of the beam iterable protocol.
// Returns an error for other protocols (such as state backed).
func iterableDecoderForArray(rt reflect.Type, decodeToElem typeDecoderFieldReflect) func(reflect.Value, io.Reader) error {
	return func(ret reflect.Value, r io.Reader) error {
		// (1) Read count prefixed encoded data
		size, err := DecodeInt32(r)
		if err != nil {
			return err
		}
		n := int(size)
		if rt.Len() != n {
			return errors.Errorf("len mismatch decoding a %v: want %d got %d", rt, rt.Len(), n)
		}
		switch {
		case n >= 0:
			if err := decodeToIterable(ret, r, decodeToElem); err != nil {
				return err
			}
			return nil
		default:
			return errors.Errorf("unable to decode array iterable with size: %d", n)
		}
	}
}

func decodeToIterable(rv reflect.Value, r io.Reader, decodeTo typeDecoderFieldReflect) error {
	size := rv.Len()
	for i := 0; i < size; i++ {
		iv := rv.Index(i)
		if decodeTo.addr {

View on GitHub (pinned to 12126d8942)

Solutions

Ensure writer and reader agree on the exact array type and length
Re-encode the data after changing array length
Use a slice instead of a fixed array if the length can vary

Example fix

// before
type Batch struct { Items [5]int }
// after (if data has variable length)
type Batch struct { Items []int }

Defensive patterns

Strategy: validation

Validate before calling

if rt.Kind() == reflect.Array {
    return fmt.Errorf("fixed array coder requires exact length match; prefer a slice for variable-length data")
}

Type guard

func isSlice(t reflect.Type) bool { return t.Kind() == reflect.Slice }

Try / catch

if err != nil && strings.Contains(err.Error(), "len mismatch decoding") {
    return fmt.Errorf("array length changed between encode and decode: %w", err)
}

Prevention

Use slices instead of fixed-size arrays for variable-length data
Never change an array length N without re-encoding existing data
Keep element type definitions in a shared package used by all stages

When it happens

Trigger: Decoding an iterable stream into a fixed-size array [N]T when the encoded size field is not N — e.g. the writer encoded a slice of a different length, or the element type changed between write and read.

Common situations: Changing a pipeline's element type from []T to [N]T (or resizing N) while replaying old data; schema drift between producer and consumer stages.

Related errors

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