Pular para o conteúdo principal
Última atualização em

Solução de problemas UNITY_CATALOG_INITIALIZATION_FAILED

Esta página descreve como diagnosticar e resolver o erro UNITY_CATALOG_INITIALIZATION_FAILED no pipeline Databricks .

Visão geral​

UNITY_CATALOG_INITIALIZATION_FAILED É um erro genérico que aparece quando Unity Catalog não consegue inicializar o armazenamento para um pipeline ou carga de trabalho durante startup cluster . Apesar do nome, a falha geralmente não é causada por uma configuração incorreta Unity Catalog . Em vez disso, quase sempre indica um problema subjacente de infraestrutura: um problema de rede que impede o cluster de alcançar o plano de controle Databricks ou um problema de permissões que impede o acesso ao armazenamento cloud que suporta o metastore do Unity Catalog .

Este erro ocorre em vários produtos Databricks, incluindo os pipelines do LakeFlow Connect, os Pipelines Declarativos do LakeFlow Spark e o AI Search.

Mensagem de erro geral​

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.

A mensagem de erro instrui você a verificar a configuração do seu Unity Catalog , mas a causa raiz geralmente é um problema de permissões de rede ou cloud , conforme descrito nas seções a seguir.

Causas raiz e soluções​

Causa : Durante a inicialização, Unity Catalog se conecta diretamente a um hostname Databricks regional (por exemplo, nvirginia.cloud.databricks.com) em vez de usar o URL workspace . Em VPCs gerenciadas pelo cliente com PrivateLink, a URL workspace é roteada corretamente através da cadeia CNAME do PAS para o endpoint VPC privada. No entanto, o hostname regional ignora completamente essa cadeia.

Se a opção "Nomes DNS privados" do endpoint da VPC não estiver habilitada, o hostname regional será resolvido para um endereço IP público. Em VPCs sem um gateway NAT (como aqueles com todo o tráfego de saída roteado através de um firewall), isso faz com que a conexão falhe com um erro de Reset, que aparece como UNITY_CATALOG_INITIALIZATION_FAILED.

Resolução :

  1. No Console de Gerenciamento AWS , navegue até VPC > endpoint e abra o endpoint VPC para seu workspace Databricks .

  2. Verifique se a opção "Nomes DNS privados ativados" está definida como "Sim" . Quando ativado, AWS cria automaticamente uma zona hospedada privada do Route 53 para cloud.databricks.com associada à sua VPC, para que nomes de host regionais como nvirginia.cloud.databricks.com sejam resolvidos para IPs privados.

  3. Se os nomes DNS privados não estiverem ativados, verifique se sua VPC atende aos pré-requisitos:

    • enableDnsSupport está definido para true
    • enableDnsHostnames está definido para true

  4. Habilite os nomes DNS privados no endpoint e verifique se o hostname regional agora resolve para um IP privado dentro da sua VPC.

Para obter mais informações, consulte Configurar a conectividade privada clássica com o Databricks e Configurar o DNS para AWS Inbound Private Link.

Permissões S3 ausentes no armazenamento Unity Catalog​

Causa : A IAM role associada aos clusters compute serverless não possui as permissões necessárias para acessar o bucket S3 que armazena o metastore do seu Unity Catalog . A inicialização Unity Catalog tenta acessar o caminho interno __unitystorage dentro deste bucket. Uma resposta 403 do S3 durante este acesso causa UNITY_CATALOG_INITIALIZATION_FAILED.

Resolução :

  1. Identifique o bucket S3 que está armazenando o seu metastore Unity Catalog . Isso é visível nos logs de erro como um caminho do tipo s3://[BUCKET]/__unitystorage/....

  2. No Console de Gerenciamento AWS , verifique se a IAM role usada pelos seus clusters serverless tem as seguintes permissões nesse bucket:

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

  3. Se você usar uma configuração de conectividade de rede (NCC) para conectividade privada com o S3, verifique se a regra de endpoint privado da NCC abrange o bucket do metastore do UC e se o estado da conexão do endpoint é Estabelecido .

  4. Reinicie o pipeline após efetuar quaisquer alterações.

Para obter mais informações sobre como configurar a conectividade privada S3 para cargas de trabalho serverless , consulte Configurar conectividade privada com a AWS - gerenciar recurso.

O recursoUnity Catalog não está configurado corretamente.​

Causa : O catálogo, esquema ou conexão referenciado pelo pipeline não existe ou não está acessível a partir do workspace. Este é o caso descrito pela própria mensagem de erro e é menos comum do que os problemas de infraestrutura mencionados acima.

Resolução :

  1. Verifique se o catálogo e o esquema referenciados no pipeline existem e estão acessíveis a partir do workspace. No Databricks, vá para Catálogo e confirme que o catálogo está visível e que você tem pelo menos privilégios USE CATALOG e USE SCHEMA .
  2. Se você estiver usando LakeFlow Connect, verifique se a conexão usada pelo pipeline é válida. Acesse Catálogo > Dados Externos > Conexões e confirme se a conexão está listada e acessível.
  3. Verifique se o cluster ou pipeline possui os privilégios necessários Unity Catalog . Consulte a seção sobre privilégios de gerenciamento no Unity Catalog.
Nesta página