メインコンテンツまでスキップ
に最終更新

UNITY_CATALOG_INITIALIZATION_FAILED のトラブルシューティング

このページでは、 DatabricksパイプラインのUNITY_CATALOG_INITIALIZATION_FAILEDエラーを診断して解決する方法について説明します。

概要​

UNITY_CATALOG_INITIALIZATION_FAILED これは、クラスターの起動中にUnity Catalogパイプラインまたはワークロードのストレージを初期化できないときに表示されるキャッチオール エラーです。 その名称とは裏腹に、このエラーは通常、 Unity Catalog設定ミスが原因ではありません。 むしろ、これはほとんどの場合、根本的なインフラストラクチャの問題を示しています。つまり、 がDatabricksコントロール プレーンに到達できないネットワークの問題、またはUnity Catalogメタストアを支えるクラウド ストレージへのアクセスを妨げる権限の問題です。

このエラーは、LakeFlow Connectパイプライン、LakeFlow Spark宣言型パイプライン、およびAI検索を含む、複数のDatabricks製品で発生します。

一般的なエラーメッセージ​

Encountered an error with Unity Catalog while setting up the pipeline on cluster [CLUSTER_ID].
Ensure that your Unity Catalog configuration is correct, and that required resources
(e.g., catalog, schema) exist and are accessible. Also verify that the cluster has
appropriate permissions to access Unity Catalog.

エラーメッセージではUnity Catalog設定を確認するように指示されていますが、根本的な原因は多くの場合、以下のセクションで説明するように、ネットワークまたはクラウドの権限の問題です。

根本原因と解決策​

原因 ：初期化中に、Unity Catalog はワークスペース URL を経由するのではなく、リージョン Databricks ホスト名 (例: nvirginia.cloud.databricks.com ) に直接接続します。PrivateLink を使用した顧客管理 VPC では、ワークスペース URL が PAS CNAME チェーンを通じてプライベートVPCエンドポイントに正しくルーティングされます。 しかし、地域ホスト名はこの経路を完全に迂回します。

VPCエンドポイントの プライベートDNS名 オプションが有効になっていない場合、リージョンホスト名はパブリックIPアドレスに解決されます。NATゲートウェイのないVPC（すべての送信トラフィックがファイアウォールを経由してルーティングされるVPCなど）では、これにより接続がリセットエラーで失敗し、 UNITY_CATALOG_INITIALIZATION_FAILEDとして表示されます。

解決 ：

  1. AWS マネジメントコンソールで、 [VPC] > [エンドポイント] に移動し、Databricks ワークスペースの VPC エンドポイントを開きます。

  2. プライベート DNS 名が有効になっている ことが 「はい」 に設定されていることを確認してください。有効にすると、AWS は自動的に VPC に関連付けられたcloud.databricks.com用の Route 53 プライベート ホスト ゾーンを作成し、 nvirginia.cloud.databricks.comのようなリージョン ホスト名がプライベート IP に解決されるようにします。

  3. プライベートDNS名 が有効になっていない場合は、VPCが前提条件を満たしていることを確認してください。

    • enableDnsSupport 設定されています true
    • enableDnsHostnames 設定されています true

  4. エンドポイントで プライベートDNS名 を有効にし、リージョンホスト名がVPC内のプライベートIPアドレスに解決されることを確認してください。

詳細については、 Databricksへの従来のプライベート接続の設定」およびAWSインバウンドプライベートリンクのDNSの設定」を参照してください。

Unity CatalogストレージのS3権限が不足しています​

原因 : サーバレス コンピュート クラスターに関連付けられたIAMロールには、 Unity CatalogメタストアをバックアップするS3バケットにアクセスするために必要な権限がありません。 Unity Catalog初期化では、このバケット内の内部パス__unitystorageへのアクセスを試みます。 このアクセス中にS3から403応答が返されると、 UNITY_CATALOG_INITIALIZATION_FAILEDが発生します。

解決 ：

  1. Unity Catalogメタストアの基盤となっているS3バケットを特定してください。 これはエラーログにs3://[BUCKET]/__unitystorage/...という形式のパスとして表示されます。

  2. AWSマネジメント コンソールで、サーバレス クラスターで使用されるIAMロールにそのバケットに対する次の権限があることを確認します。

    • s3:GetObject
    • s3:PutObject
    • s3:DeleteObject
    • s3:ListBucket
    • s3:GetBucketLocation

  3. S3 へのプライベート接続にネットワーク接続構成 (NCC) を使用する場合は、NCC のプライベートエンドポイントルールが UC メタストアバケットをカバーしていること、およびエンドポイントの接続状態が Established で あることを確認してください。

  4. 変更を加えた後は、パイプラインを再起動してください。

サーバーレス ワークロードのプライベートS3接続の構成の詳細については、 「AWS 管理のリソースへのプライベート接続の構成」を参照してください。

Unity Catalogリソースが正しく構成されていません​

原因 ：パイプラインが参照するカタログ、スキーマ、または接続が存在しないか、ワークスペースからアクセスできません。これはエラーメッセージ自体が説明しているケースであり、上記のインフラストラクチャの問題よりも発生頻度は低い。

解決 ：

  1. パイプラインで参照されているカタログとスキーマが存在し、ワークスペースからアクセスできることを確認してください。Databricksで カタログ に移動し、カタログが表示されていること、および少なくともUSE CATALOGとUSE SCHEMA権限を持っていることを確認してください。
  2. LakeFlow Connectを使用している場合は、パイプラインで使用されている接続が有効であることを確認してください。 カタログ > 外部データ > 接続 に移動し、接続が一覧に表示され、アクセス可能であることを確認してください。
  3. クラスターまたはパイプラインに必要なUnity Catalog権限があることを確認します。 Unity Catalogの「権限の管理」を参照してください。
このページの見出し