apache/beam · error

decoding time.Time schema override

Error message

decoding time.Time schema override

What it means

This error wraps a failure to read the 1-field Beam schema row header while decoding a time.Time value using the Beam schema override registered in sdks/go/pkg/beam/encoding.go. The timeDec override reads a simple row header before the encoded time bytes; if the stream does not begin with the expected header, the read fails and the underlying error is wrapped with this message. It indicates the byte stream being decoded is not a valid schema-encoded time.Time.

Source

Thrown at sdks/go/pkg/beam/encoding.go:288

		t := iface.(time.Time)
		// We use the text marshalling rather than the binary marshalling
		// since it has more precision. Apparently some info isn't included
		// in the binary marshal.
		data, err := t.MarshalText()
		if err != nil {
			return fmt.Errorf("marshalling time: %v", err)
		}
		if err := coder.EncodeBytes(data, w); err != nil {
			return err
		}
		return nil
	}, nil
}

func timeDec(reflect.Type) (func(io.Reader) (any, error), error) {
	return func(r io.Reader) (any, error) {
		if err := coder.ReadSimpleRowHeader(1, r); err != nil {
			return nil, errors.Wrap(err, "decoding time.Time schema override")
		}
		data, err := coder.DecodeBytes(r)
		if err != nil {
			return nil, errors.Wrap(err, "retrieving time data: %v")
		}
		t := time.Time{}
		if err := t.UnmarshalText(data); err != nil {
			return nil, errors.Wrap(err, "decoding time: %v")
		}
		return t, nil
	}, nil
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Regenerate the encoded data with the same Beam version (re-run the encoding side of the pipeline).
2. Verify the stream is decoded with the registered schema override for time.Time, not a generic decoder.
3. Inspect the wrapped underlying error (via errors.Wrap chain) to see whether it is EOF/truncation versus a header mismatch.
4. If using custom serialization, ensure bytes are produced with coder.WriteSimpleRowHeader(1) followed by coder.EncodeBytes.

Example fix

// before: decoding arbitrary bytes as time.Time
v, err := decodeAsBytes(raw)
// after: ensure data was encoded by the beam time.Time override
if len(raw) < 1 { return fmt.Errorf("empty payload for time.Time") }
t, err := decodeTimeOverride(raw) // uses ReadSimpleRowHeader + DecodeBytes

if len(raw) == 0 {
    return fmt.Errorf("empty payload: cannot decode time.Time override")
}

if err := decodeTime(raw); err != nil {
    if strings.Contains(err.Error(), "decoding time.Time schema override") {
        return fmt.Errorf("corrupt time.Time payload: %w", err)
    }
    return err
}

When it happens

Trigger: Calling beam decoding (e.g. via schema encoding/decoding of a pipeline element) on a byte stream containing a time.Time field where the data is corrupt, truncated, or was not produced by the matching timeEnc override.

Common situations: Corrupt or hand-crafted encoded blobs, mixed Beam SDK versions where the row-header format changed, or decoding data written by a custom encoder that skips ReadSimpleRowHeader.

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
• decoding a %v
• error decoding []byte field
• retrieving time data: %v
• decoding time: %v

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