apache/iceberg · critical · IllegalStateException

Cannot find Dynamo catalog table %s

Error message

Cannot find Dynamo catalog table %s

What it means

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.

Source

Thrown at aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbCatalog.java:667

        .retry(CATALOG_TABLE_CREATION_WAIT_ATTEMPTS_MAX)
        .throwFailureWhenFinished()
        .onlyRetryOn(IllegalStateException.class)
        .run(this::checkTableActive);
  }

  private void checkTableActive(String tableName) {
    try {
      DescribeTableResponse response =
          dynamo.describeTable(DescribeTableRequest.builder().tableName(tableName).build());
      TableStatus currentStatus = response.table().tableStatus();
      if (!currentStatus.equals(TableStatus.ACTIVE)) {
        throw new IllegalStateException(
            String.format(
                "Dynamo catalog table %s is not active, current status: %s",
                tableName, currentStatus));
      }
    } catch (ResourceNotFoundException e) {
      throw new IllegalStateException(
          String.format("Cannot find Dynamo catalog table %s", tableName));
    }
  }

  private boolean updateProperties(
      Namespace namespace,
      String updateExpression,
      Map<String, AttributeValue> attributeValues,
      Map<String, String> attributeNames) {
    validateNamespace(namespace);
    Map<String, AttributeValue> key = namespacePrimaryKey(namespace);
    try {
      GetItemResponse response =
          dynamo.getItem(
              GetItemRequest.builder()
                  .tableName(awsProperties.dynamoDbTableName())
                  .consistentRead(true)
                  .key(key)

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. 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`).
2. Fix s3.table.dynamo-db-table-name and region configuration to point at the existing catalog table.
3. Verify with `aws dynamodb describe-table --table-name <name>` in the same account/region the application uses.

Example fix

// before
config.put("s3.table.dynamo-db-table-name", "iceberg_catalog_v1"); // never created

// after
aws dynamodb create-table --table-name iceberg_catalog_v1 \
  --attribute-definitions AttributeName=Catalog,AttributeType=S AttributeName=Namespace,AttributeType=S AttributeName=TableIdentifier,AttributeType=S \
  --key-schema AttributeName=Catalog,KeyType=HASH AttributeName=Namespace,KeyType=RANGE AttributeName=TableIdentifier,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

try {
  dynamo.describeTable(DescribeTableRequest.builder().tableName(catalogTable).build());
} catch (ResourceNotFoundException e) {
  throw new IllegalStateException("Catalog table " + catalogTable + " missing; create it before initializing the catalog", e);
}

try {
  catalog.initialize(config);
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Cannot find Dynamo catalog table")) {
    createCatalogTableIfMissing(catalogTableName);
    catalog.initialize(config);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Cannot find table %s to drop
• Cannot rename table %s to %s: %s does not exist
• Cannot find default warehouse location: namespace %s does no
• Cannot create namespace %s: already exists
• Cannot find namespace %s

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/0f79ce67372a69af. Report an issue: GitHub.