apache/beam · error

error decoding BSON: %w

Error message

error decoding BSON: %w

What it means

Returned by the generic helper decodeBSON in mongodbio when bson.Unmarshal fails to deserialize stored BSON bytes into the target type. This typically means the bytes are corrupt/truncated or the target Go type no longer matches the schema that was encoded.

Source

Thrown at sdks/go/pkg/beam/io/mongodbio/coder.go:74

	return encodeBSON(in)
}
func decodeRange(in []byte) (idRange, error) {
	return decodeBSON[idRange](in)
}

func encodeBSON[T any](in T) ([]byte, error) {
	out, err := bson.Marshal(in)
	if err != nil {
		return nil, fmt.Errorf("error encoding BSON: %w", err)
	}

	return out, nil
}

func decodeBSON[T any](in []byte) (T, error) {
	var out T
	if err := bson.Unmarshal(in, &out); err != nil {
		return out, fmt.Errorf("error decoding BSON: %w", err)
	}

	return out, nil
}

func encodeObjectID(objectID primitive.ObjectID) []byte {
	return objectID[:]
}

func decodeObjectID(bytes []byte) primitive.ObjectID {
	var out primitive.ObjectID

	copy(out[:], bytes[:])

	return out
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the restriction/range struct shape is unchanged from when the state was encoded (schema evolution breaks decode).
2. Inspect the wrapped bson error to identify the mismatched field/type.
3. If resuming an old checkpoint is not required, restart the pipeline fresh to re-encode state.
4. Add bson tags so old and new field names stay compatible across versions.

Example fix

// before: renamed field breaks decode of old state
splitFn struct { offset int64 }

// after: keep encoded name
type splitFn struct { Start int64 `bson:"start"`; offset int64 }

// verify round-trip after any schema change:
out, err := bson.Marshal(r)
if err == nil { _, err = bson.Unmarshal(out, &target) }
// err != nil => schema drift, fix before deploying

r, err := decodeBSON[splitRestriction](state)
if err != nil {
    return fmt.Errorf("decoding split restriction (schema changed?): %w", err)
}

When it happens

Trigger: Calling decodeBSON (via decodeRestriction/decodeRange) on state bytes produced with an older/different struct schema, or on corrupted checkpoint state.

Common situations: Changing restriction/range struct fields between pipeline resume/checkpoint runs; upgrading mongo-driver with changed BSON handling; truncated state bytes.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• error encoding BSON: %w
• error decoding document ID: %w
• error decoding document: %w
• mongodbio.newReadFn: %v
• fraction must be between 0 and 1

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