{"record":{"id":"3d175276afd18d9c","repo":"apache/beam","slug":"error-decoding-document-w","errorCode":null,"errorMessage":"error decoding document: %w","messagePattern":"error decoding document: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/io/mongodbio/read.go","lineNumber":317,"sourceCode":"\t\tSetSort(bson.M{\"_id\": 1})\n\n\tcursor, err := fn.collection.Find(ctx, filter, opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error executing find command: %w\", err)\n\t}\n\n\treturn cursor, nil\n}\n\nfunc decodeDocument(cursor *mongo.Cursor, t reflect.Type) (id any, value any, err error) {\n\tvar docID documentID\n\tif err := cursor.Decode(&docID); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"error decoding document ID: %w\", err)\n\t}\n\n\tout := reflect.New(t).Interface()\n\tif err := cursor.Decode(out); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"error decoding document: %w\", err)\n\t}\n\n\tvalue = reflect.ValueOf(out).Elem().Interface()\n\n\treturn docID.ID, value, nil\n}\n","sourceCodeStart":299,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/mongodbio/read.go#L299-L324","documentation":"After extracting the _id, decodeDocument decodes the full document into a newly allocated value of the user's element type via reflection. If cursor.Decode(out) fails, the error is wrapped as 'error decoding document'. This means the MongoDB document's fields cannot be mapped onto the Go type the user configured for the read (missing/bad bson tags, type mismatches).","triggerScenarios":"cursor.Decode(out) fails while reading: a document field's BSON type does not match the target Go struct field (e.g. string into int), a required bson tag is wrong, a field is a BSON type the Go type cannot accept, or the cursor yields an invalid document mid-stream.","commonSituations":"Evolving schemas: a field stored as int historically but string for newer documents; bson tag typos after refactor; reading a collection written by another service with different field types; time.Time vs primitive.DateTime mismatches.","solutions":["Compare the failing document's field types against the target struct's bson tags and fix the struct or use bson.M/raw decoding","Normalize the collection's schema so each field has a consistent BSON type","Add a custom decode hook / UnmarshalBSON on the target type for flexible types","Update the mongo-driver for better type coercion and clearer decode errors","Filter out incompatible documents in the read query while migrating"],"exampleFix":"// before\ntype Event struct {\n\tCount string `bson:\"count\"` // stored as int in Mongo\n}\n// after\ntype Event struct {\n\tCount int `bson:\"count\"`\n}","handlingStrategy":"validation","validationCode":"// dry-run decode one document into the target type before launching\nprobe := reflect.New(t).Interface()\nif err := coll.FindOne(ctx, filter).Decode(probe); err != nil {\n\treturn fmt.Errorf(\"element type incompatible: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"out := reflect.New(t).Interface()\nif err := cursor.Decode(out); err != nil {\n\treturn nil, nil, fmt.Errorf(\"row %v: %w\", docID.ID, err)\n}","preventionTips":["Keep bson tags in sync with the collection schema","Constrain fields to consistent BSON types at write time","Dry-run decode a sample document before full pipelines","Add custom UnmarshalBSON for fields with evolving types"],"tags":["mongodb","go","bson","decoding","schema"],"backgroundTag":"bson-decode-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}