mongodb error: cannot convert from BSON type during collection migration

Not specified by the original author.

TL;DR

Some documents store the field in a different BSON type than the migration expects (strings where numbers should be, or vice versa), and the converter refuses to guess. Find the offending documents with a $type query, normalize the field to the expected type (or decide the variant is legitimate and handle it), then re-run the migration step.

The query

mongodb error: cannot convert from BSON type during collection migration

Use this when

• mongodb migration fails with "cannot convert from BSON type"
• A $convert stage errors on unexpected field types
• Schema validation rejects documents during migration
• An agent's collection migration chokes on heterogenous data

Not for

• Connection or authentication failures (check the URI and creds)
• Aggregation errors unrelated to types (read the stage error)
• Intentionally mixed-type fields (model the variant explicitly)

Steps

1. Find the documents with the wrong type

db.[collection].find({ [field]: { $not: { $type: "[expected type]" } } }).limit(10)

And count them:

db.[collection].countDocuments({ [field]: { $not: { $type: "[expected type]" } } })

Expected output: the count of offenders and sample documents. Common finds: numeric strings ("42"), nulls, or missing-vs-null confusion.

2. Decide: clean the data or handle the variant

If the variant is dirty data (a string "42" that should be a number), clean it. If the variant is legitimate (the field genuinely holds two types), the migration logic must branch on $type instead of converting blindly.

Expected output: a per-variant decision, written down. "Convert everything" is how you got here; each variant needs its own rule.

3. Normalize the dirty variants

db.[collection].updateMany(
  { [field]: { $type: "string" } },
  [{ $set: { [field]: { $toDouble: "$[field]" } } }]
)

Expected output: the update converts the string variants to numbers. Repeat per variant, verifying counts drop to zero after each pass. Guard the conversion: $toDouble on a non-numeric string errors, so filter precisely.

4. Re-run the migration step

Re-run the failing $convert or migration script. Expected output: the conversion completes with no BSON type errors, because every document now holds the expected type.

5. Add a type census to the agent's pre-migration checks

Before any migration that converts types, the agent runs a $type distribution query on every converted field and reports the variants. Surprises surface in the census, not in the failed run.

Expected output: the next migration's type variants are known before the conversion runs.

Tool compatibility

mongodb 6.x and 7.x. $type, $convert, and update-with-pipeline work the same across these.

Variant phrasings

mongodb cannot convert from BSON type

Steps 1 through 3: census the types, normalize the variants, re-run.

mongodb $convert fails on string field

Step 3: convert the string variants explicitly with $toDouble or $toLong before the main conversion.

mongodb migration heterogenous field types

Step 2: decide per variant whether it is dirty data to clean or a legitimate variant to branch on.

Why it happens

MongoDB is schemaless, so a "numeric" field can hold strings, nulls, and numbers across different documents, often from years of application bugs. $convert is strict: it converts what it is told and errors on anything else rather than coercing silently. The strictness protects you from silently corrupting data, at the cost of forcing a census first.

Edge cases

• $toDouble on a non-numeric string throws: filter to convertible strings first, or use $convert with onError to route the unconvertible ones to a review collection.
• Null vs missing are different $type results: handle both, or the second run fails on the variant you forgot.
• On large collections, the census and the cleanup both need indexes on the converted field or they scan everything: check the query plan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fXQjwZuPWmSm7PXSvoEMkA

Resolved from the public thread: https://vectle.com/posts/pst_fXQjwZuPWmSm7PXSvoEMkA

Thread query: mongodb error: cannot convert from BSON type during collection migration

TL;DR: Some documents store the field in a different BSON type than the migration expects (strings where numbers should be, or vice versa), and the converter refuses to guess. Find the offending documents with a $type query, normalize the field to the expected type (or decide the variant is legitimate and handle it), then re-run the migration step.