Aller au contenu principal
Dernière mise à jour le

Dépannage de UNITY_CATALOG_INITIALIZATION_FAILED

Cette page décrit comment diagnostiquer et résoudre l'erreur UNITY_CATALOG_INITIALIZATION_FAILED dans les pipelines Databricks.

Présentation​

UNITY_CATALOG_INITIALIZATION_FAILED Il s’agit d’une erreur générique qui apparaît lorsque Unity Catalog ne peut pas initialiser le stockage pour un pipeline ou une charge de travail pendant le Startup du cluster. Malgré son nom, la défaillance n’est généralement pas causée par une mauvaise configuration de Unity Catalog. Au lieu de cela, cela indique presque toujours un problème d'infrastructure sous-jacent : un problème de réseau empêchant le cluster d'atteindre le control plane de Databricks, ou un problème d'autorisations empêchant l'accès au stockage cloud servant de support au métastore Unity Catalog.

Cette erreur survient dans plusieurs produits Databricks, y compris les pipelines Lakeflow Connect, les LakeFlow Pipelines et la Recherche IA.

Message d’erreur général​

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.

Le message d'erreur vous invite à vérifier votre configuration Unity Catalog, mais la cause principale est souvent un problème de réseautage ou d'autorisations cloud, comme décrit dans les sections suivantes.

Causes principales et résolutions​

Cause : lors de l'initialisation, Unity Catalog se connecte directement à un Hostname Databricks régional (par exemple, nvirginia.cloud.databricks.com) plutôt que via l'URL du Workspace. Dans les Virtual Private Cloud (VPC) gérés par les clients avec PrivateLink, l'URL du Workspace est correctement acheminée via la chaîne PAS CNAME vers l'Endpoint Virtual Private Cloud (VPC) privé. Cependant, le Hostname régional contourne entièrement cette chaîne.

Si l'option Noms DNS privés de l'Endpoint Virtual Private Cloud (VPC) n'est pas activée, le Hostname régional se résout en une adresse IP publique. Dans les VPC sans passerelle NAT (tels que ceux où tout le trafic sortant est acheminé via un pare-feu), cela provoque l'échec de la connexion avec une erreur de Reset, qui apparaît sous la forme de UNITY_CATALOG_INITIALIZATION_FAILED.

Résolution :

  1. Dans la console de gestion AWS, accédez à VPC > Endpoints et ouvrez l'Endpoint VPC de votre Databricks Workspace.

  2. Vérifiez que Noms DNS privés activés est défini sur Oui . Lorsqu'elle est activée, AWS crée automatiquement une zone hébergée privée Route 53 pour cloud.databricks.com associée à votre VPC, afin que les hostnames régionaux comme nvirginia.cloud.databricks.com résolvent en adresses IP privées.

  3. Si les noms DNS privés ne sont pas activés, vérifiez que votre Virtual Private Cloud (VPC) remplit les conditions préalables :

    • enableDnsSupport est défini sur true
    • enableDnsHostnames est défini sur true

  4. Activez les **noms DNS privés** sur l'endpoint et vérifiez que le hostname régional se résout désormais en une adresse IP privée au sein de votre Virtual Private Cloud (VPC).

Pour plus d'informations, consultez Configurer la connectivité privée classique à Databricks et Configurer le DNS pour Private Link AWS entrant.

Autorisations S3 manquantes sur le stockage Unity Catalog​

Cause : Le rôle IAM associé aux clusters de compute Serverless ne dispose pas des autorisations nécessaires pour accéder au compartiment S3 qui prend en charge votre metastore Unity Catalog. L'initialisation d'Unity Catalog tente d'accéder au chemin __unitystorage interne dans ce compartiment. Une réponse 403 de S3 lors de cet accès entraîne UNITY_CATALOG_INITIALIZATION_FAILED.

Résolution :

  1. Identifiez le bucket S3 qui prend en charge votre métastore Unity Catalog. Ceci est visible dans les logs d'erreurs sous la forme d'un chemin s3://[BUCKET]/__unitystorage/....

  2. Dans la Console de gestion AWS, vérifiez que le rôle IAM utilisé par vos clusters serverless dispose des autorisations suivantes sur ce compartiment :

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

  3. Si vous utilisez une configuration de connectivité réseau (NCC) pour une connectivité privée à S3, vérifiez que la règle de l'Endpoint privé de la NCC couvre le compartiment du metastore UC et que l'état de connexion de l'Endpoint est Établi .

  4. Redémarrez le pipeline après avoir apporté des modifications.

Pour plus d'information sur la configuration de la connectivité S3 privée pour les charges de travail Serverless, voir Configurer la connectivité privée aux ressources gérées par AWS.

Les ressources Unity Catalog ne sont pas configurées correctement​

Cause : le catalogue, le schéma ou la connexion référencé(e) par le pipeline n'existe pas ou n'est pas accessible depuis le workspace. C'est le cas décrit par le message d'erreur lui-même et il est moins courant que les problèmes d'infrastructure mentionnés ci-dessus.

Résolution :

  1. Vérifiez que le catalogue et le schéma référencés dans le pipeline existent et sont accessibles depuis le Workspace. Dans Databricks, accédez à Catalogue et confirmez que le catalogue est visible et que vous disposez d'au moins les privilèges USE CATALOG et USE SCHEMA.
  2. Si vous utilisez Lakeflow Connect, vérifiez que la connexion utilisée par le pipeline est valide. Accédez à Catalogue > Données externes > Connexions et vérifiez que la connexion est répertoriée et accessible.
  3. Vérifiez que le cluster ou le pipeline dispose des privilèges Unity Catalog nécessaires. Consultez Gérer les privilèges dans Unity Catalog.
Sur cette page