What causes "decoding a *%v" in apache/beam?

Compare the writer's schema with the reader's struct and reconcile fields

decoding a *%v

Error message

decoding a *%v

What it means

The row decoder for pointer-to-struct types wraps any non-EOF decode error with "decoding a *%v". It allocates a new value of type t, decodes into its element, and returns the wrapped error if field decoding fails. io.EOF is deliberately re-raised unwrapped so callers can detect clean end-of-stream. The wrapped error means the encoded row bytes did not match the expected struct layout.

Source

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

	// Pointers become the value type for decomposition.
	if t.Kind() == reflect.Ptr {
		isPtr = true
		t = t.Elem()
	}
	dec, err := b.decoderForStructReflect(t)
	if err != nil {
		return nil, err
	}

	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

View on GitHub (pinned to 12126d8942)

Solutions

Compare the writer's schema with the reader's struct and reconcile fields
Check the wrapped underlying error to find the offending field
Re-encode the data after schema changes, or use compatible field evolution
Ensure both pipeline stages use the same Beam version

Defensive patterns

Strategy: try-catch

Validate before calling

// verify schema compatibility before decoding
if !schemasCompatible(writerSchema, readerSchema) {
    return fmt.Errorf("writer schema %v incompatible with reader struct %T", writerSchema, reader)
}

Try / catch

v, err := decodeRowPtr(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", err)
}

Prevention

Keep writer and reader struct definitions in a shared package
Handle io.EOF separately — it passes through unwrapped
Re-encode data after schema changes; avoid silent field retyping
Pin the same Beam version across pipeline stages

When it happens

Trigger: Decoding a row stream into *T where a field's bytes fail to decode — schema mismatch, truncated data, or the wrong coder used at write time.

Common situations: Schema evolution (field added/removed/retyped) between writer and reader; replaying data encoded by an older Beam version; reading a stream written by an entirely different coder.

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

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