📋

Description

This error indicates that a field name in a MongoDB document contains a dot (`.`). MongoDB reserves the dot notation for accessing fields within embedded documents. Using dots in top-level or embedded field names directly can lead to parsing errors or unexpected behavior during document manipulation and querying.

💬

Error Message

Dotted Field Name

🔍

Known Causes

3 known causes

⚠️

Invalid Field Name Character

Attempting to use a dot (`.`) directly within a field name, which is a reserved character for navigating embedded documents.

⚠️

Data Import Field Naming

Importing data from external sources where field names might contain dots that are incompatible with MongoDB's naming conventions.

⚠️

Application-Generated Field Names

An application or script dynamically generates field names that inadvertently include dots, violating MongoDB's naming rules.

🛠️

Solutions

3 solutions available

1. Rename Fields with Dots easy

Modify documents to use valid field names by removing dots.

1

Identify documents containing dotted field names. You can use the aggregation framework for this, although direct identification might be challenging if the error occurs during an operation.

db.collection.aggregate([
  { $project: { fields: { $objectToArray: "$$ROOT" } } },
  { $unwind: "$fields" },
  { $match: { "fields.k": /\./ } },
  { $group: { _id: "$_id" } }
])

2

For each identified document, update it by creating new fields without dots and copying the data from the dotted fields. Then, remove the old dotted fields.

db.collection.updateMany(
  { _id: ObjectId("your_document_id") },
  [
    { $set: {
        "newFieldName": "$old.dotted.field",
        "anotherNewField": "$another.dotted.field"
      }
    },
    { $unset: ["old.dotted.field", "another.dotted.field"] }
  ]
)

3

If this error is occurring during application writes, modify your application code to construct documents with valid field names, avoiding the use of dots.

// Example of incorrect field naming in application code
let data = { "user.name": "Alice" };

// Example of correct field naming
let correctData = { "userName": "Alice" };

2. Use `$addFields` with `$$ROOT` to Reconstruct Documents medium

Reconstruct documents using `$addFields` to rename dotted fields to valid ones.

1

Create a new collection to store the corrected documents. This is a safer approach than modifying in place, especially for large datasets.

db.collection.aggregate([
  { $addFields: {
      "newFieldName": "$old.dotted.field",
      "anotherNewField": "$another.dotted.field"
    }
  },
  { $project: { "old.dotted.field": 0, "another.dotted.field": 0 } } // Exclude original dotted fields
], {
  allowDiskUse: true // Use if dealing with large datasets
}).forEach(function(doc) {
  db.newCollection.insertOne(doc);
});

2

Once the new collection is populated, you can rename or drop the original collection and rename the new collection to replace it.

db.collection.rename("collection_old");
db.newCollection.rename("collection");

3. Address Dotted Field Names in Application Logic medium

Modify your application's data handling to avoid creating or querying with dotted field names.

1

Review all parts of your application that interact with MongoDB, including data insertion, updates, and queries.

null

2

If your application uses an ORM or ODM, check its configuration and data models to ensure they don't inadvertently create dotted field names.

// Example: Mongoose schema definition
// Incorrect: { 'user.name': String }
// Correct: { userName: String }

3

When performing writes, ensure that the keys in your JSON objects are valid MongoDB field names. For example, instead of `{'user.address': '123 Main St'}`, use `{'userAddress': '123 Main St'}`.

// In your application code (e.g., Node.js with a MongoDB driver):
const doc = {
  user: {
    name: "John Doe"
  },
  contactInfo: {
    email: "john.doe@example.com"
  }
};
db.collection.insertOne(doc);

4

When querying, ensure you are referencing field names correctly without dots.

// Incorrect query:
db.collection.find({'user.name': 'John Doe'})

// Correct query:
db.collection.find({'userName': 'John Doe'})

🔗

Related Errors

5 related errors

MongoDB Error 57: Dotted Field Name Usage