apache/beam · error

decoding a %v

Error message

decoding a %v

What it means

The row decoder for struct (non-pointer) types wraps any non-EOF decode error with "decoding a %v", after decoding into a freshly allocated value. Like the pointer variant, io.EOF passes through unwrapped for end-of-stream detection. It signals that the encoded row bytes could not be decoded into the target struct type.

Source

Thrown at sdks/go/pkg/beam/core/graph/coder/row_decoder.go:122

	if isPtr {
		return func(r io.Reader) (any, error) {
			rv := reflect.New(t)
			err := dec(rv.Elem(), r)
			// Wrap handles nil cases, but io.EOF should be checked explicitly.
			if err == io.EOF {
				return nil, err
			}
			return rv.Interface(), errors.Wrapf(err, "decoding a *%v", t)
		}, nil
	}
	return func(r io.Reader) (any, error) {
		rv := reflect.New(t)
		err := dec(rv.Elem(), r)
		// Wrap handles nil cases, but io.EOF should be checked explicitly.
		if err == io.EOF {
			return nil, err
		}
		return rv.Elem().Interface(), errors.Wrapf(err, "decoding a %v", t)
	}, nil
}

// decoderForStructReflect returns a reflection based decoder function for the
// given struct type.
func (b *RowDecoderBuilder) decoderForStructReflect(t reflect.Type) (func(reflect.Value, io.Reader) error, error) {
	var coder typeDecoderReflect
	coder.typ = t
	for i := 0; i < t.NumField(); i++ {
		i := i // avoid alias issues in the closures.
		sf := t.Field(i)
		isUnexported := sf.PkgPath != ""
		if sf.Anonymous {
			ft := sf.Type
			if ft.Kind() == reflect.Ptr {
				// If a struct embeds a pointer to an unexported type,
				// it is not possible to set a newly allocated value
				// since the field is unexported.

View on GitHub (pinned to 12126d8942)

Solutions

1. Align writer and reader struct definitions/schemas
2. Inspect the wrapped underlying error for the failing field
3. Re-encode affected data after schema changes
4. Pin matching Beam versions across stages

v, err := decodeRow(r)
if err != nil {
    if errors.Is(err, io.EOF) { return nil, io.EOF }
    return nil, fmt.Errorf("row decode failed for %T, check schema drift: %w", v, err)
}

When it happens

Trigger: Decoding a row stream into T where a field fails to decode due to layout/schema mismatch, a truncated stream, or a coder mismatch between the write and read sides.

Common situations: Schema drift between pipeline stages; reading data written with a different Beam version or a non-row coder; byte corruption in shuffle storage.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• decoding a *%v
• error decoding document: %w
• unable to decode slice iterable with size: %d
• len mismatch decoding a %v: want %d got %d
• unable to decode array iterable with size: %d

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