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|Editorial standard: source-backed technical guidance
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.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.
Decision Support
Compare Guide
403 Forbidden vs 404 Not Found: When to Hide Resources
Use 403 for explicit access denial, or 404 to conceal resource existence when security policy requires reducing endpoint and object enumeration risk.
Compare Guide
404 Not Found vs 410 Gone: Missing vs Permanent Removal
Learn when to return 404 (missing or temporary absence) versus 410 (intentional permanent removal), including redirect and cache implications.
Playbook
Resource State Playbook (404 / 410 / ResourceNotFound)
Use this playbook to separate temporary missing-resource lookups from permanent removals, then fix scope, lifecycle, and identifier drift safely.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.