How do I troubleshoot Apache Iceberg table errors with Athena?

Resolution

Follow the troubleshooting steps for the error that you're experiencing.

Unsupported table property key

This error occurs when the TBLPROPERTIES clause of the CREATE TABLE or ALTER TABLE statement doesn't use a supported table property. When you're creating or modifying Iceberg tables, Athena allows only a predefined list of key-value pairs in the table properties.

To resolve this issue, make sure that your Iceberg table uses supported table properties.

Athena can't generate the CREATE TABLE statement because the table has unsupported properties

You get an "UNSUPPORTED" error when Athena can't reproduce the table structure because you used the SHOW CREATE TABLE DDL statement in your query. Instead, use the DESCRIBE FORMATTED DDL statement to show the table properties.

You receive the "TABLE_REDIRECTION_ERROR" error

This error occurs with Athena SELECT queries that use unsupported Iceberg table metadata. Make sure that your Athena SELECT query contains supported Query Iceberg table metadata.

You receive the "Unsupported Hive type" error

This error occurs when you use an unsupported data type with an Iceberg table. For example, you might receive the "SHORT, use integer" error because Iceberg tables don't support the tinyint or smallint Athena data types. Or, you might receive the "CHAR, use string" error because Iceberg tables don't support char Athena data types.

To resolve this issue, confirm that your Athena query is using a supported data type for Iceberg tables.

You receive the "ICEBERG_COMMIT_ERROR" error

This error might occur when multiple statements try to modify the same set of files that run in parallel for Iceberg table updates. For example, when multiple DELETE statements in parallel to try to delete the same set of records at the same time.

To avoid this issue, take the following actions:

• Make sure that query updates run sequentially to avoid parallel data processing.
• Implement a retry mechanism with exponential backoff when you update Iceberg tables.

Note: Athena supports only AWS Glue optimistic locking. When you modify an Iceberg table with other lock methods, you might cause data loss and break transactions. For more information, see Optimistic locking on the Apache Iceberg website.

You receive the "NOT_SUPPORTED: Iceberg table updates require at least format version 2" error

This error occurs when you try the DELETE operation on a version 1 Iceberg table. Athena creates and operates only on version 2 Iceberg tables. Make sure that your Iceberg table uses the Athena engine version 2. If you use another type of engine, then set the format-version table property to 2 to allow row-level deletes. For example, use version 2 when you write an Iceberg table and register it to the AWS Glue Data Catalog. For more information, see Delete formats on the Apache Iceberg website.

You receive the "GENERIC_INTERNAL_ERROR:" error

You receive the following error message:

"GENERIC_INTERNAL_ERROR: com.amazonaws.trino.exceptions.UnrecoverableS3OperationException: com.amazonaws.services.s3.model.AmazonS3Exception: The specified key does not exist"

This error occurs when you delete a metadata file, such as a manifest list or metadata.json. The Athena query then fails. If you can't successfully recover the file, then roll back the table to a snapshot or timestamp.

Note: You must roll back the table in an Apache Spark environment, such as AWS Glue or Amazon EMR, not the Athena query editor.

To roll back the table to a specific snapshot ID, run the roll_to_snapshot Apache Iceberg command:

CALL catalog_name.system.rollback_to_snapshot('your-db.your-table', your-snapshot-id)

Note: Replace your-db, your-table, and your-snapshot-id with your values.

To roll back the table to a specific timestamp, run the rollback_to_timestamp Apache Iceberg command:

CALL catalog_name.system.rollback_to_timestamp('your-db.your-table', TIMESTAMP 'yyyy-mm-dd hh:mm:ss')

Note: Replace your-db, your-table, and yyyy-mm-dd hh:mm:ss with your values.

For more information, see rollback_to_snapshot and rollback_to_timestamp on the Apache Iceberg website.

Related information

Troubleshoot issues in Athena

How can I use Apache Iceberg with a cross-account AWS Glue Data Catalog in Spark?

Query Apache Iceberg tables