The ProblemYou'll see this error when MongoDB tries to index a field that exceeds the 1,024-byte limit of the WiredTiger storage engine. It usually crops up during a createIndex() operation on an existing collection. It also happens when you insert a document into a collection that already indexes a long string, such as a 2,000-character URL or a base64-encoded image string.
The exact error message looks like this:
WiredTigerIndex::insert: key too large to index, failing 1024 { : "..." }
In versions older than MongoDB 4.2, this limit is a hard wall. If a single indexed field hits 1,025 bytes, your write operation or index creation will fail immediately.
Identify the Problem DocumentsBefore you can fix the schema, you need to find the specific documents breaking the rules. Use the aggregation framework to calculate the byte length of the problematic field. Here is a script to find any field exceeding 1,000 bytes:
db.your_collection.aggregate([
{ $project: { field_length: { $strLenBytes: "$yourField" }, yourField: 1 } },
{ $match: { field_length: { $gt: 1000 } } },
{ $sort: { field_length: -1 } }
])
Don't confuse bytes with characters. While a standard 'A' is 1 byte, a single emoji like 🚀 takes up 4 bytes. This means a string of only 256 emojis will trigger the 1,024-byte error.
Solutions### 1. Use a Hashed IndexA hashed index is your best bet if you only need equality matches—like looking up a specific long URL. Instead of indexing the massive string itself, MongoDB indexes a fixed-size hash of the value. This bypasses the 1,024-byte limit entirely.
// Drop the failing B-tree index first
db.your_collection.dropIndex("yourField_1")
// Create a hashed index instead
db.your_collection.createIndex({ yourField: "hashed" })
2. Use a Text IndexSwitch to a text index if you need to search for keywords within the string rather than matching the whole value perfectly. Text indexes break the string into individual tokens. Since each token is usually small, you won't hit the 1,024-byte limit for the field as a whole.
db.your_collection.createIndex({ yourField: "text" })
3. The Legacy Workaround (MongoDB 4.0 and below)If you cannot change your index type immediately, you can tell MongoDB to simply skip indexing documents that are too large. This prevents the database from throwing an error, but there is a catch: those documents won't show up in queries that use that index.
db.getSiblingDB("admin").runCommand({
setParameter: 1,
failIndexKeyTooLong: false
})
Note that MongoDB 4.2 removed this parameter. Newer versions handle large keys more gracefully by default, though they still face performance penalties.
4. Hash the Data in Your CodeSometimes you need exact matches but want to stick with a standard B-tree index for performance. In this case, hash the field in your application logic (using SHA-256, for example) before saving it. Store this 64-character hash in a separate field and index that instead.
// Node.js example
const crypto = require('crypto');
const longValue = "...very long string...";
const hashedValue = crypto.createHash('sha256').update(longValue).digest('hex');
db.collection.insertOne({
original_field: longValue,
field_hash: hashedValue
});
// Index the small, fixed-length hash
db.collection.createIndex({ field_hash: 1 });
VerificationOnce you've applied a fix, verify that the index is actually being used. Run explain() on your typical query to see the execution plan:
db.your_collection.find({ yourField: "some_value" }).explain("executionStats")
Look at the winningPlan. If you used a hashed index, the stage should be IXSCAN. Double-check nReturned to ensure your queries are finding the documents you expect.