Fix IndexNotFoundException in DynamoDB Queries (2026)

The IndexNotFoundException in DynamoDB means the query operation couldn’t find the specified index, which is usually an IndexName or a ProjectionExpression that implies an index.

Common Causes and Fixes for IndexNotFoundException

1. Incorrect IndexName Provided:

   • Diagnosis: Check the exact spelling and case of the IndexName in your query request against the actual index names defined for your table. You can list your table’s indexes using the AWS CLI:

     aws dynamodb list-indexes --table-name YourTableName
     

   • Fix: Ensure the IndexName in your Query API call or SDK method matches one of the names returned by the list-indexes command precisely. For example, if the CLI shows "index-name": "my-gsi-example", your query must use IndexName: "my-gsi-example".
   • Why it works: DynamoDB is case-sensitive for index names. A simple typo or case mismatch prevents it from locating the index metadata.

2. Index Not Yet Active:

   • Diagnosis: Global Secondary Indexes (GSIs) take time to provision and become active after creation. Check the status of your index using the AWS CLI:

     aws dynamodb describe-table --table-name YourTableName --query "Table.GlobalSecondaryIndexes[?IndexName=='YourIndexName'].IndexStatus" --output text
     

     Look for IndexStatus: ACTIVE. If it’s CREATING or UPDATING, the index is not ready.
   • Fix: Wait for the index status to be ACTIVE. You can poll the describe-table command or use CloudWatch alarms to notify you when it becomes active. Attempting to query an inactive GSI will result in IndexNotFoundException.
   • Why it works: DynamoDB prevents queries against indexes that are still being built or updated to ensure data consistency and prevent partial results.

3. Querying a Local Secondary Index (LSI) with Wrong IndexName:

   • Diagnosis: LSIs are created at the same time as the table and share the same provisioned throughput. Their IndexName is often omitted in Query operations, relying on the partition key to implicitly target the LSI if it shares the same partition key as the base table. However, if you explicitly provide an IndexName for an LSI, it must be correct. Use describe-table to confirm:

     aws dynamodb describe-table --table-name YourTableName --query "Table.LocalSecondaryIndexes"
     

   • Fix: If you are explicitly specifying an IndexName for an LSI, ensure it matches the name shown in the describe-table output. If you’re not specifying an IndexName and your query uses the base table’s partition key, it should implicitly use the LSI if one exists with that partition key. If you need to query a different LSI, you must provide its correct IndexName.
   • Why it works: While LSIs are tightly coupled with the base table, DynamoDB still requires accurate identification if an IndexName parameter is used, especially if multiple LSIs share partition keys.

4. Misunderstanding ProjectionExpression for Index Targeting:

   • Diagnosis: A ProjectionExpression defines which attributes are copied into an index. It is not used to specify which index to query. The IndexName parameter is the sole determinant of which index a query targets. If you are seeing IndexNotFoundException and you haven’t specified an IndexName, DynamoDB is attempting to query the base table.
   • Fix: If you intend to query a specific index (GSI or LSI), you must provide the IndexName parameter in your query request. The ProjectionExpression is a separate concern for controlling index size and cost.
   • Why it works: The IndexName parameter tells DynamoDB which data structure (base table or a specific index) to use for the query execution. ProjectionExpression only affects the data within that structure.

5. Using an Index that was Deleted:

   • Diagnosis: If an index was previously active but has since been deleted, any application code or configuration still referencing its IndexName will fail. Verify the index still exists using aws dynamodb list-indexes --table-name YourTableName.
   • Fix: Remove any references to the deleted index’s name from your application’s query logic, configuration files, or infrastructure-as-code definitions.
   • Why it works: The IndexName is a unique identifier. If that identifier no longer exists in DynamoDB’s metadata for the table, the system cannot find it.

6. Region Mismatch in SDK Configuration:

   • Diagnosis: While less common for IndexNotFoundException specifically (more typical for ResourceNotFoundException), if your AWS SDK client is configured for the wrong region, it might be trying to access indexes on a table that doesn’t exist or has a different index configuration in that region. Double-check your SDK client’s region configuration.
   • Fix: Ensure your AWS SDK client is initialized with the correct region where your DynamoDB table and its indexes reside. For example, in Python’s Boto3:

     import boto3
     dynamodb = boto3.resource('dynamodb', region_name='us-east-1')
     

   • Why it works: DynamoDB tables and their indexes are region-specific. The SDK needs to communicate with the correct regional endpoint to find and query your resources.

The next error you’ll likely encounter after fixing IndexNotFoundException is ValidationException if your query parameters (like KeyConditionExpression or FilterExpression) are malformed for the index you are now successfully targeting.