TableNotFoundException
AWS TableNotFoundException indicates that the DynamoDB operation targeted a table name that does not exist in the specific AWS Region and Account provided in the client configuration.
Last reviewed: March 20, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Table Not Found Mean?
TableNotFoundException is DynamoDB's way of saying: "The name is valid, but I do not see it here." It is distinct from ResourceNotFoundException (a broader AWS error) and is common in DynamoDB Streams or older API versions. Because DynamoDB is a regional service, a table named "Orders" in us-east-1 is invisible to a client configured for us-west-2.
Common Causes
- -Region Mismatch: The table was created in
us-east-1, but the application client is defaulted tous-west-2. - -Case Sensitivity: Attempting to call
orders-prodwhen the actual table name isOrders-Prod. - -Environment Drift: The CI/CD pipeline deployed code to Production, but the environment variables are still pointing to a Staging table name that does not exist in the Prod account.
- -Infrastructure Delay: Attempting to query a table via a script before the Terraform/CDK stack has finished the
CreateTableoperation.
How to Fix Table Not Found
- 1Audit the Region: Explicitly set the
regionin your SDK client to match the table's location. - 2Exact Name Matching: Run
aws dynamodb list-tablesin your CLI and copy-paste the result to avoid typos or casing errors. - 3Check Env Vars: Ensure your
DYNAMODB_TABLE_NAMEvariable is correctly resolved at runtime (not just in your.envfile). - 4Cross-Account Verification: Ensure your IAM role is assuming the correct account identity where the table resides.
Step-by-Step Diagnosis for Table Not Found
- 1Run
aws dynamodb list-tables --region <your-region>to confirm the table is visible in the target account. - 2Log the table name and region at application startup to catch template rendering errors (e.g.,
${TABLE_NAME}literally). - 3Check the IAM Policy: Ensure the identity has
dynamodb:DescribeTablepermissions; sometimes a lack of permission can mask as a "not found" in specific SDK versions. - 4Verify the table status: If the table was recently deleted or is in
DELETINGstatus, it will trigger this error.
The "Invisible Table" Checklist
- -Is the Region correct? (Check
AWS_REGIONenv var). - -Is the Case correct? (Orders vs orders).
- -Is the Account correct? (Verify via
sts get-caller-identity).
Environment Variable Pitfalls
- -In Kubernetes or Docker, ensure secrets are mounted correctly. A "missing" environment variable often defaults to an empty string or the variable name itself, leading to
TableNotFoundException.
Implementation Examples
// Ensure region and name are coming from a verified source
const client = new DynamoDBClient({
region: process.env.AWS_REGION || 'us-east-1'
});
const TABLE_NAME = process.env.MY_TABLE_NAME;
if (!TABLE_NAME) throw new Error("DYNAMODB_TABLE_NAME is missing!");aws dynamodb list-tables --region us-east-1 --query "TableNames"
# If your table is not in this list, your region/account is wrong.Seen in Production
The "Staging vs. Prod" Ghost
Frequency: high
Example: A developer merges code that works in Staging. In Production, the table prefix is prd- instead of stg-. The app crashes because it is looking for the staging table in the prod account.
Fix: Use environment-aware configuration mapping or IaC-driven naming.
Debugging Tools
- -AWS CLI `list-tables`: The fastest way to see what AWS sees.
- -AWS CloudTrail: To see the exact ARN and table name being requested by the SDK.
- -IAM Policy Simulator: To ensure you have permissions to see the table.
How to Verify the Fix
- -Run
aws dynamodb describe-table --table-name <name>: If this succeeds, your configuration is now correct. - -Verify that the application can perform a simple
GetItemorPutItemwithout errors. - -Confirm that all environments (Dev/Test/Prod) have their specific table names mapped correctly.
How to Prevent Recurrence
- -Fail-Fast Startup Check: Implement a small "ping" (DescribeTable) at app boot. If the table is not found, crash the app immediately with a clear log.
- -IaC Outputs: Use Terraform outputs or CDK
CfnOutputto inject table names directly into your compute environment, eliminating manual entry. - -SSM Parameter Store: Store table names in SSM and resolve them by path (e.g.,
/prod/services/order-api/table-name). - -Pro-tip: Treat your DynamoDB client as a "Singleton" that is initialized with a verified region from a central config to prevent region drift across different modules.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.