Troubleshooting using Apache Iceberg™ tables with Snowflake Open Catalog in Snowflake¶

The following scenarios can help you troubleshoot issues that might occur when using Apache Iceberg™ tables with Snowflake Open Catalog in Snowflake.

您无法为 Open Catalog 创建目录集成¶

本部分描述了在为 Open Catalog 创建目录集成时，如何进行故障排除。

要进行故障排除，请识别在目录集成创建失败时您在 SQL 输出中收到的错误消息。

Error	SQL Execution Error: Cannot create catalog integration <catalog_integration_name> due to error: Unable to process: Unable to find warehouse <catalog_name>. Check the REST configuration and ensure the warehouse name '<catalog_name>' matches the Polaris catalog name.
Cause	The `<open_catalog_name>` you specified for the `CATALOG_NAME` parameter in your catalog integration doesn’t match the name of any external catalog in the Open Catalog account at the `<polaris_account_url>` you specified for the `CATALOG_URI` parameter.
Solution	Update `<open_catalog_name>` for the `CATALOG_NAME` parameter to exactly match the name of the external catalog in Open Catalog, and try creating the catalog integration again. If you haven’t created the external catalog yet, follow the instructions in Create a catalog. Important `<open_catalog_name>` is case-sensitive.

Error	SQL Execution Error: User provided authentication credentials are invalid for catalog integration <catalog_integration_name> due to error: Malformed request: unauthorized_client: The client is not authorized.
Cause	The OAuth token you specified in the catalog integration isn’t valid.
Solution	Ensure that the values specified for `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` in your catalog integration are valid values for an existing service connection. To validate, compare these values with the service credential values you saved when you configured the service connection. If they don’t match, update the values to match.

您无法创建 Snowflake 管理的表¶

本部分描述了在创建 Snowflake 管理的表时，如何进行故障排除。

要进行故障排除，请识别在创建表时失败时您在 SQL 输出中收到的错误消息。

Error

SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The Snowflake service
connection associated with the Polaris catalog integration does not have the required privileges to send notifications. The
minimum required privileges are TABLE_CREATE, TABLE_WRITE_PROPERTIES, TABLE_DROP, NAMESPACE_CREATE, and NAMESPACE_DROP.

Cause

您要连接到的外部目录的目录角色没有必要的权限，无法向 Open Catalog 发送通知。

Solution

Update the catalog role by granting all of the following privileges to the catalog role for your external catalog:

TABLE_CREATE
TABLE_WRITE_PROPERTIES
TABLE_DROP
NAMESPACE_CREATE
NAMESPACE_DROP

目录角色的更新位置取决于是在目录、命名空间还是在表级别应用授权。请参阅适用于您的目录角色的过程：

Error

SQL Execution Error: Failed to access the REST endpoint of catalog integration <catalog_integration_name> with error: Unable to
process: Failed to get subscoped credentials: Error assuming AWS_ROLE:
User: <IAM_user_arn> is not authorized to perform: sts:AssumeRole on resource: <S3_role_arn>. Check the accessibility of the REST
catalog URI or warehouse.

Cause The AWS IAM user for your external catalog can’t assume the role that has permission to access S3.

Solution

Modify the policy document in AWS to allow the IAM user for your Open Catalog account to assume the role that has permission to access your S3 bucket. To modify the policy document, you need to update the IAM role in AWS. For details, see Retrieve the AWS IAM user for your Snowflake Open Catalog account and then Grant the IAM user permissions to access bucket objects.

请记住，策略文档必须包括外部卷和 Open Catalog 中外部目录的 IAM 用户 ARN 和外部 ID。在以下示例策略文档中，请注意以下值：

arn:aws:iam::111111111111:user/----0000-s is the STORAGE_AWS_IAM_USER_ARN for the external volume.
arn:aws:iam::222222222222:user/----0000-s is the IAM user ARN for the external catalog in Snowflake Open Catalog.
Iceberg_table_external_id is the STORAGE_AWS_EXTERNAL_ID for your external volume and also the external ID for your external Catalog in Open Catalog.

{
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
               "arn:aws:iam::111111111111:user/----0000-s",
               "arn:aws:iam::222222222222:user/----0000-s"
            ]
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "iceberg_table_external_id"
           }
         }
       }
     ]
   }

Error

SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris
catalog cannot be of type INTERNAL.

Cause

您正在尝试将 Snowflake 管理的表同步到 Open Catalog 中的内部目录。您只能将 Snowflake 管理的表同步到 Open Catalog 中的外部目录。

Solution

您无法将现有的内部目录更新为外部目录，因此您必须创建一个新的外部目录：

Follow the instructions in Create a catalog to create an external catalog in your Open Catalog account. When creating the catalog, ensure that the External toggle is enabled.

Update <open_catalog_name> for the CATALOG_NAME parameter in your catalog integration to the name of the external catalog you created.

Error	SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: SQL Execution Error: Resource on the REST endpoint of catalog integration CATINT is forbidden due to error: Forbidden: Invalid locations '[<path to metadata file>]' for identifier '<identifier>': <path to metadata file> is not in the list of allowed locations: [<list of allowed locations>].
Cause	您要创建的表的元数据文件路径不在您的外部云提供商允许的位置列表中。因此，Open Catalog 无法访问表的元数据文件。
Solution	Ensure that the location of the metadata file falls under the file path of the default base location for the catalog that the service admin created in Open Catalog, or that it falls under any of the additional allowed locations, if applicable. For the list of allowed locations, select the catalog in Open Catalog and refer to the Locations field.

您无法在指定 CATALOG_SYNC 参数时更改 Iceberg 表¶

本部分描述了在更改 CATALOG_SYNC 参数时，如何进行故障排除。

要进行故障排除，请识别在表更改失败时您在 SQL 输出中收到的错误消息。

Error

SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The Snowflake service
connection associated with the Polaris catalog integration does not have the required privileges to send notifications. The minimum
required privileges are TABLE_CREATE, TABLE_WRITE_PROPERTIES, TABLE_DROP, NAMESPACE_CREATE, and NAMESPACE_DROP.

Cause

您要连接到的外部目录的目录角色没有必要的权限，无法向 Open Catalog 发送通知。

Solution

Grant all of the following privileges to the catalog role for your external catalog:

TABLE_CREATE
TABLE_WRITE_PROPERTIES
TABLE_DROP
NAMESPACE_CREATE
NAMESPACE_DROP

目录角色的更新位置取决于其授权是应用于目录、命名空间还是表级别。请参阅适用于您的目录角色的过程：

Error

SQL Execution Error: Failed to access the REST endpoint of catalog integration <catalog_integration_name> with error: Unable to
process: Failed to get subscoped credentials: Error assuming AWS_ROLE:
User: <IAM_user_arn> is not authorized to perform: sts:AssumeRole on resource: <S3_role_arn>. Check the accessibility of the REST
catalog URI or warehouse.

Cause The AWS IAM user for your external catalog doesn’t have permission to access S3 bucket objects.

Solution

Modify the policy document in AWS to allow the IAM user for your Open Catalog account to access objects in your S3 bucket. To modify the policy document, you need to update the IAM role in AWS. For details, see Retrieve the AWS IAM user for your Polaris Open Catalog account and then Grant the IAM user permissions to access bucket objects.

请记住，策略文档必须包括外部卷和 Open Catalog 中外部目录的 IAM 用户 ARN 和外部 ID。在以下示例策略文档中，请注意以下值：

arn:aws:iam::111111111111:user/----0000-s is the STORAGE_AWS_IAM_USER_ARN for the external volume
arn:aws:iam::222222222222:user/----0000-s is the IAM user ARN for the external catalog in Snowflake Open Catalog.
Iceberg_table_external_id is the STORAGE_AWS_EXTERNAL_ID for your external volume and also the external ID for your external catalog in Open Catalog.

{
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
               "arn:aws:iam::111111111111:user/----0000-s",
               "arn:aws:iam::222222222222:user/----0000-s"
            ]
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "iceberg_table_external_id"
           }
         }
       }
     ]
   }

Error

SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris
catalog cannot be of type INTERNAL.

Cause

您正在尝试将 Snowflake 管理的 Iceberg 表同步到 Open Catalog 中内部目录的目录集成。您只能将 Snowflake 管理的 Iceberg 表同步到 Open Catalog 中的外部目录。

Solution

您无法将现有的内部目录更新为外部目录，因此您必须创建一个新的外部目录：

Follow the instructions in Create a catalog to create an external catalog in your Open Catalog account. When creating the catalog, ensure that the External toggle is enabled.
Update open_catalog_name for the CATALOG_NAME parameter in your catalog integration to the name of the external catalog you created.

Error	SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: SQL Execution Error: Resource on the REST endpoint of catalog integration CATINT is forbidden due to error: Forbidden: Invalid locations '[<path to metadata file>]' for identifier '<identifier>': <path to metadata file> is not in the list of allowed locations: [<list of allowed locations>].
Cause	您要创建的表的元数据文件路径不在您的外部云提供商允许的位置列表中。因此，Open Catalog 无法访问表的元数据文件。
Solution	Ensure that the location of the metadata file falls under the file path of the default base location for the catalog that the service admin created in Open Catalog, or that it falls under any of the additional allowed locations, if applicable. For the list of allowed locations, select the catalog in Open Catalog and refer to the Locations field.