What just happened
You tried to save a document and MongoDB threw this:
MongoServerError: The dotted field 'user.name' in 'data.user.name' is not valid for storage.
The reason is a fundamental MongoDB rule: dot notation (parent.child) is how MongoDB navigates nested documents. When a field key itself contains a dot, MongoDB can't distinguish between a nested path and a literal key name — so it refuses to store it entirely.
Nine times out of ten this comes from unsanitized user input, a CSV/JSON import, or a third-party API response. The keys look fine in your code, but they sneak a dot in somewhere along the way.
Reproducing the problem
Here's the minimal case in Node.js:
// Node.js — mongodb driver
const doc = {
data: {
'user.name': 'Alice' // dot inside the key!
}
};
await collection.insertOne(doc);
// → MongoServerError: The dotted field 'user.name' in 'data.user.name'
// is not valid for storage.
It's not just insertOne. The same error fires on updateOne, findOneAndUpdate, replaceOne — any write that passes a document containing dotted keys, however deeply nested.
Finding where the dots are
Before picking a fix, map out every offending key. A small recursive helper does this in seconds:
// JavaScript — find all dotted keys in an object
function findDottedKeys(obj, path = '') {
for (const key of Object.keys(obj)) {
const fullPath = path ? `${path}.${key}` : key;
if (key.includes('.')) {
console.warn('Dotted key found:', fullPath);
}
if (obj[key] !== null && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
findDottedKeys(obj[key], fullPath);
}
}
}
findDottedKeys(doc);
// Dotted key found: data.user.name
Run this on your payload before saving while you debug. Once you know the scope — one field or fifty — pick the approach below that fits.
Fix 1 — Replace dots in keys with a safe character
Swap every dot in key names for an underscore (or another delimiter) before writing to MongoDB:
// JavaScript — recursively sanitize keys
function sanitizeKeys(obj) {
if (Array.isArray(obj)) {
return obj.map(sanitizeKeys);
}
if (obj !== null && typeof obj === 'object') {
return Object.fromEntries(
Object.entries(obj).map(([k, v]) => [
k.replace(/\./g, '_'), // dot → underscore
sanitizeKeys(v)
])
);
}
return obj;
}
const safe = sanitizeKeys(doc);
await collection.insertOne(safe);
Pick a delimiter that won't collide with real key names. Common choices: _, a middle dot · (U+00B7), or a Unicode escape like \u2024. Whatever you pick, write it down — you'll need the reverse mapping when you read the data back.
Fix 2 — Restructure to a proper nested document
Sometimes a dotted key like user.name was always meant to be a nested field. If that's the case, just make the nesting explicit:
// Before (wrong)
const bad = { data: { 'user.name': 'Alice' } };
// After (correct nested structure)
const good = { data: { user: { name: 'Alice' } } };
await collection.insertOne(good);
This is the cleanest option when the source data was simply formatted oddly. As a bonus, queries become more natural — { 'data.user.name': 'Alice' } works exactly as MongoDB intends.
Fix 3 — Store dynamic keys as an array of key-value pairs
Got truly unpredictable field names — form submissions, analytics events, user-defined config? Don't fight MongoDB's key rules. Use an array instead:
// Instead of: { 'user.name': 'Alice', 'user.email': 'a@b.com' }
// Store as:
const doc = {
attributes: [
{ key: 'user.name', value: 'Alice' },
{ key: 'user.email', value: 'a@b.com' }
]
};
await collection.insertOne(doc);
Querying is more verbose ({ attributes: { $elemMatch: { key: 'user.name', value: 'Alice' } } }), but the schema stays valid regardless of what keys arrive from external sources. For high-cardinality attribute sets this also avoids index explosion.
Python / pymongo
Same error, same root cause:
# pymongo
from pymongo import MongoClient
client = MongoClient('mongodb://localhost:27017/')
col = client.mydb.mycollection
doc = {'data': {'user.name': 'Alice'}}
col.insert_one(doc)
# raises: pymongo.errors.WriteError:
# The dotted field 'user.name' in 'data.user.name' is not valid for storage.
The Python fix mirrors the JavaScript one:
def sanitize_keys(obj):
if isinstance(obj, list):
return [sanitize_keys(i) for i in obj]
if isinstance(obj, dict):
return {
k.replace('.', '_'): sanitize_keys(v)
for k, v in obj.items()
}
return obj
safe_doc = sanitize_keys(doc)
col.insert_one(safe_doc)
Mongoose (Node.js ODM)
Using Mongoose with a Mixed or Schema.Types.Mixed field? Add a pre-save hook so sanitization happens automatically on every write:
schema.pre('save', function (next) {
if (this.data) {
this.data = sanitizeKeys(this.data);
this.markModified('data');
}
next();
});
Verifying the fix
Three quick checks confirm everything worked:
// 1. Insert a test document
const result = await collection.insertOne(sanitizeKeys(testDoc));
console.log('Inserted ID:', result.insertedId);
// 2. Read it back
const stored = await collection.findOne({ _id: result.insertedId });
console.log(JSON.stringify(stored, null, 2));
// Keys should show underscores (or nested structure), no dots
// 3. Confirm no dotted keys remain
findDottedKeys(stored); // Should print nothing
Insert succeeds, stored document looks right, and findDottedKeys stays silent — you're done.
Preventing this upstream
- Validate at the boundary — reject or sanitize dotted keys before they reach your database layer. Schema validators like Joi or Zod can enforce key-format rules at the API entry point, where it's cheapest to catch them.
- Don't expose raw user-defined keys — if users can name their own fields, route through Fix 3 (the
{ key, value }array pattern) rather than letting arbitrary strings become document keys. - MongoDB 5.0+ partially relaxed this restriction — dots and dollar signs are allowed in field names in some aggregation contexts via operators like
$setField. Plain insert/update still rejects them at the driver level, though. Sanitize in your application; don't rely on version-specific server behavior.