How do I troubleshoot index creation failures in my Amazon DocumentDB cluster?

Resolution

Amazon DocumentDB allows you to create only one index at a time per collection. However, you can use parallel index updates to load data into multiple collections simultaneously. It's a best practice to create indexes first and then load the data.

Amazon DocumentDB supports background index creation and foreground index creation.

Monitor Index progress status

Index creation progresses through multiple stages, including initialization, scanning collections, sorting keys, and inserting keys.

To monitor the index progress status, run the following query:

db.currentOp({
  "command.createIndexes": { 
    $exists: true 
  }
})

The preceding command outputs percentage completion, scanned blocks, and sorted or inserted keys for each stage. When the last stage reaches 100% completion, Amazon DocumentDB has successfully created all indexes. You can monitor index progress status when you use Amazon DocumentDB versions 5.0 and later. For more information, see Managing Amazon DocumentDB indexes.

Resolve the "Command failed with error 14031: 'Not enough disk space' on server" error

Amazon Document uses a DB instance's available FreeLocalStorage to create an index based on the instance class of the primary resource. The storage size needed depends on the size of the index that you create. If the FreeLocalStorage value decreases during index creation, then the index creation might slow down and you might receive the following error message:

"Command failed with error 14031: 'Not enough disk space' on server."

To monitor the available storage, set up an Amazon CloudWatch alarm for the FreeLocalStorage metric. If you want to create an index on a large collection, then it's a best practice to scale up the instance class before you create the index. Then scale back after the index creation is complete.

Resolve the "Existing index build in progress on the same collection. Collection is limited to a single index build at a time" error

Amazon DocumentDB supports only one background index creation at a time per collection. For example, if you try to run multiple DDL operations such as createIndex() or dropIndex() simultaneously on one collection you might receive the following error message:

"Existing index build in progress on the same collection. Collection is limited to a single index build at a time."

To prevent the preceding error, run only one background index creation at a time per collection.

To review your ongoing index creations, run the following query:

db.currentOp({
  "command.createIndexes": {
    $exists : true
  }
})

Resolve the "Key too large to index" error

If you create an index with a key size greater than 2048 bytes, then index creation fails with the "key too large to index" error. For more information on key size limits, see Amazon DocumentDB quotas and limits.

Resolve the "createIndex error: namespace name generated from index name is too long" error

When you try to migrate from MongoDB to Amazon DocumentDB with an index name that exceeds 255 characters, the index creation fails. Then you receive the following error message:

"createIndex error: namespace name generated from index name is too long."

To resolve this error, review the Amazon DocumentDB naming constraints.

Resolve issues caused by throttling

Resource throttling on your DB instance can cause index operations to fail. Before you create an index, make sure that there's no throttling in the CPU, memory, DBConnections, and FreeLocalStorage. Use CloudWatch graphs and Performance Insights to validate your instance load before you create indexes.

Resolve issues caused by long running transactions

Long running transactions in your Amazon DocumentDB cluster can delay or cause index creation to fail.

To check which transactions are currently in progress, run the following query:

db.currentOp({
  "active": true,
   $and: [
    { 
      op: "command", 
      "command.createIndexes": {
        $exists: true
       }
      }
     ]
   })

Resolve the "createIndex error: Field 'weights' is currently not supported" error

When you restore data from MongoDB that includes a text type index, the index creation fails with the following error:

"createIndex error: Field 'weights' is currently not supported."

The text index type is not supported for Amazon DocumentDB versions lower than 5.0. To resolve this issue, drop the text index or change the index to a supported type in the source server. Then create a fresh data dump and restore the new dump to Amazon DocumentDB.

Resolve the "unsupported_index_options" error

You can use Amazon DocumentDB versions 3.6 and later to create 2dsphere and Amazon DocumentDB version 5 and later to create partial index. When you try to create a partial index or 2dsphere on a unsupported version, you receive the following error:

"unsupported_index_options": [ "partialFilterExpression" ] or ["2dsphereIndexVersion"]"

To avoid errors caused by unsupported index types, change the index format to a supported type, and then re-initiate the index creation.

Related information

Troubleshooting indexes

How to index on Amazon DocumentDB (with MongoDB compatibility)