ReadSimpleRowHeader field count mismatch, got %v, want %v

Error message

ReadSimpleRowHeader field count mismatch, got %v, want %v

What it means

After successfully reading the field count in ReadSimpleRowHeader, it validates that the count matches the number of fields the caller expects for the row type. This error means the header declares a different field count than the schema being decoded into — the data and the target type disagree, so decoding aborts.

Source

Thrown at sdks/go/pkg/beam/core/graph/coder/row.go:218

	}
	// Never nils, so we write the 0 byte header.
	if err := EncodeVarInt(0, w); err != nil {
		return fmt.Errorf("WriteSimpleRowHeader a 0 length nils bit field: %v", err)
	}
	return nil
}

// ReadSimpleRowHeader is a convenience function to read Beam Schema Row Headers
// for values that do not have any nil fields. Reads and validates the number of
// fields total (returning an error for mismatches, and checks that there are
// no nils encoded as a bit field.
func ReadSimpleRowHeader(fields int, r io.Reader) error {
	n, err := DecodeVarInt(r)
	if err != nil {
		return fmt.Errorf("ReadSimpleRowHeader field count: %v, %v", n, err)
	}
	if int(n) != fields {
		return fmt.Errorf("ReadSimpleRowHeader field count mismatch, got %v, want %v", n, fields)
	}
	n, err = DecodeVarInt(r)
	if err != nil {
		return fmt.Errorf("ReadSimpleRowHeader reading nils count: %v, %v", n, err)
	}
	if n != 0 {
		return fmt.Errorf("ReadSimpleRowHeader expected no nils encoded count, got %v", n)
	}
	return nil
}

View on GitHub (pinned to 12126d8942)

Solutions

Align the schema: decode with the field count the data was actually written with.
Re-serialize stored data after changing the row struct's fields.
Check Beam SDK versions between writer and reader for coder format changes.
In tests, pass the same field count used by the encoder helper (e.g. WriteSimpleRowHeader).

Example fix

// before
// struct gained a field after data was written
coder.ReadSimpleRowHeader(4, r) // data has 3 fields
// after
coder.ReadSimpleRowHeader(3, r) // match the count the data was written with

Defensive patterns

Strategy: validation

Validate before calling

// verify expected field count against the schema used when data was written
if expectedFields != writtenFields { return fmt.Errorf("schema drift: data has %d fields, decoder expects %d", writtenFields, expectedFields) }

Try / catch

err := coder.ReadSimpleRowHeader(fields, r)
if err != nil && strings.Contains(err.Error(), "field count mismatch") {
	return fmt.Errorf("row schema changed since data was written: %w", err)
}

Prevention

Re-serialize stored row data whenever the row struct's fields change.
Version serialized datasets alongside schema changes.
In tests, always pair WriteSimpleRowHeader(n, ...) with ReadSimpleRowHeader(n, ...) using the same n.

When it happens

Trigger: Calling ReadSimpleRowHeader(fields, r) where fields does not match the varint in the stream: decoding data written from a different struct/schema, after a schema change (fields added/removed), or pointing the reader at the wrong record.

Common situations: Evolving a Go struct used with the row coder without re-serializing old data; serializing in one pipeline version and decoding in another with a changed schema; unit tests with mismatched expectations.

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/d4331a78e99ce732. Report an issue: GitHub.