{"record":{"id":"0f79ce67372a69af","repo":"apache/iceberg","slug":"cannot-find-dynamo-catalog-table-s","errorCode":null,"errorMessage":"Cannot find Dynamo catalog table %s","messagePattern":"Cannot find Dynamo catalog table (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbCatalog.java","lineNumber":667,"sourceCode":"        .retry(CATALOG_TABLE_CREATION_WAIT_ATTEMPTS_MAX)\n        .throwFailureWhenFinished()\n        .onlyRetryOn(IllegalStateException.class)\n        .run(this::checkTableActive);\n  }\n\n  private void checkTableActive(String tableName) {\n    try {\n      DescribeTableResponse response =\n          dynamo.describeTable(DescribeTableRequest.builder().tableName(tableName).build());\n      TableStatus currentStatus = response.table().tableStatus();\n      if (!currentStatus.equals(TableStatus.ACTIVE)) {\n        throw new IllegalStateException(\n            String.format(\n                \"Dynamo catalog table %s is not active, current status: %s\",\n                tableName, currentStatus));\n      }\n    } catch (ResourceNotFoundException e) {\n      throw new IllegalStateException(\n          String.format(\"Cannot find Dynamo catalog table %s\", tableName));\n    }\n  }\n\n  private boolean updateProperties(\n      Namespace namespace,\n      String updateExpression,\n      Map<String, AttributeValue> attributeValues,\n      Map<String, String> attributeNames) {\n    validateNamespace(namespace);\n    Map<String, AttributeValue> key = namespacePrimaryKey(namespace);\n    try {\n      GetItemResponse response =\n          dynamo.getItem(\n              GetItemRequest.builder()\n                  .tableName(awsProperties.dynamoDbTableName())\n                  .consistentRead(true)\n                  .key(key)","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbCatalog.java#L649-L685","documentation":"DynamoDbCatalog.checkTableActive() calls DescribeTable on the DynamoDB catalog table; when DynamoDB responds with ResourceNotFoundException it is converted to an IllegalStateException with this message. This means the configured catalog backing table does not exist at all, so no catalog operations can proceed.","triggerScenarios":"Any catalog operation that calls checkTableActive when the DynamoDB table named by s3.table.dynamo-db-table-name does not exist in the configured region/account — typically because it was never created or was deleted.","commonSituations":"Pointing the catalog at a table name that was never provisioned; wrong AWS region in configuration so DescribeTable looks in the wrong partition; a cleanup job deleted the catalog table while the application was running.","solutions":["Create the DynamoDB catalog table first (e.g. `aws dynamodb create-table --table-name iceberg --attribute-definitions AttributeName=Catalog,AttributeType=S AttributeName=Namespace,AttributeType=S AttributeName=TableIdentifier,AttributeType=S --key-schema ... --billing-mode PAY_PER_REQUEST`).","Fix s3.table.dynamo-db-table-name and region configuration to point at the existing catalog table.","Verify with `aws dynamodb describe-table --table-name <name>` in the same account/region the application uses."],"exampleFix":"// before\nconfig.put(\"s3.table.dynamo-db-table-name\", \"iceberg_catalog_v1\"); // never created\n\n// after\naws dynamodb create-table --table-name iceberg_catalog_v1 \\\n  --attribute-definitions AttributeName=Catalog,AttributeType=S AttributeName=Namespace,AttributeType=S AttributeName=TableIdentifier,AttributeType=S \\\n  --key-schema AttributeName=Catalog,KeyType=HASH AttributeName=Namespace,KeyType=RANGE AttributeName=TableIdentifier,KeyType=RANGE \\\n  --billing-mode PAY_PER_REQUEST","handlingStrategy":"validation","validationCode":"try {\n  dynamo.describeTable(DescribeTableRequest.builder().tableName(catalogTable).build());\n} catch (ResourceNotFoundException e) {\n  throw new IllegalStateException(\"Catalog table \" + catalogTable + \" missing; create it before initializing the catalog\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(config);\n} catch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Cannot find Dynamo catalog table\")) {\n    createCatalogTableIfMissing(catalogTableName);\n    catalog.initialize(config);\n  } else throw e;\n}","preventionTips":["Provision the DynamoDB catalog table via IaC before deploying the app","Verify table name and region settings match across environments","Add a startup check that describe-table succeeds for the configured catalog table"],"tags":["aws","dynamodb","catalog","table-not-found","configuration"],"backgroundTag":"resource-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}