What causes "unable to decode array iterable with size: %d" in apache/beam?

Verify the coder used at encode time matches the array type at decode time

unable to decode array iterable with size: %d

Error message

unable to decode array iterable with size: %d

What it means

When decoding an array-typed iterable, after the length check the decoded size n must be >= 0; if n is negative the decoder hits the default branch and errors with "unable to decode array iterable with size: %d". Negative sizes are invalid for the fixed-size array iterable variant and indicate corrupt or incompatibly encoded data.

Source

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

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 {
			iv = iv.Addr()
		}
		if err := decodeTo.decode(iv, r); err != nil {
			return err
		}
	}
	return nil
}

View on GitHub (pinned to 12126d8942)

Solutions

Verify the coder used at encode time matches the array type at decode time
Re-encode data with a coder consistent with the target array type
Check Beam versions on the writer and reader match

Defensive patterns

Strategy: try-catch

Try / catch

v, err := decodeArray(r)
if err != nil {
    if strings.Contains(err.Error(), "unable to decode array iterable with size") {
        return nil, fmt.Errorf("array iterable stream has invalid/negative size, coder mismatch: %w", err)
    }
    return nil, err
}

Prevention

Match the coder variant (slice vs array) on both encode and decode sides
Pin the same Beam version across all pipeline stages
Treat negative size sentinels as a sign the wrong decoder is being used

When it happens

Trigger: Decoding an array iterable stream whose int32 size field is negative — usually the unknown-size sentinel written by a slice/variadic iterable being read by an array decoder.

Common situations: Coder-type mismatch: an upstream stage writes a variadic iterable (negative size sentinel) but the downstream decoder expects a fixed-size array; corrupted streams from cross-version replay.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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