Solucionar problemas da CLI do Databricks

Observação

O uso da CLI do Databricks está sujeito à Licença do Databricks e ao Aviso de Privacidade do Databricks, incluindo quaisquer disposições de Dados de Uso.

Use as informações a seguir para solucionar problemas com a CLI do Databricks.

Habilitar o registro em log

Se um comando falhar ou não produzir a saída esperada, você poderá usar o registro em log para ajudar a identificar o que pode ter dado errado. Você pode registrar mensagens que a CLI do Databricks gera sobre vários eventos de comando, avisos e erros. Para registrar essas mensagens em log, especifique as seguintes opções de comando da CLI do Databricks:

Sinalizador	Descrição
--log-file	Uma string que representa o arquivo onde gravar os logs de saída. Caso esse sinalizador não seja especificado, o padrão é registrar os logs de saída no stderr.
--log-format	text para gravar logs de saída em texto ou json para gravar logs de saída em JSON. Se esse sinalizador não for especificado, os logs de saída serão gravados como texto.
--log-level	Uma cadeia de caracteres que representa o nível de formato de log. Os níveis de log válidos são error, warn, info, debug, trace e disabled. O nível padrão é disabled, o que significa que nada é registrado. --debug é equivalente a --log-level debug.

O exemplo a seguir registra mensagens de rastreamento do comando especificado em um arquivo nomeado databricks-cli.log no formato JSON.

databricks clusters list --log-file databricks-cli.log --log-format json --log-level trace

Erro ao baixar o Terraform

Uma chave expirada em algumas versões da CLI do Databricks causa o seguinte erro ao executar databricks bundle deploy:

error downloading Terraform: unable to verify checksums signature: openpgp: key expired

Para resolver esse erro, atualize a CLI do Databricks para uma versão com patch mais recente, que atualiza o mecanismo de verificação para trabalhar com uma chave mais recente. Atualize para a versão corrigida que corresponde à versão secundária da CLI atual:

• Instalação binária: baixe a versão corrigida da página de releases do Databricks CLI no GitHub.

• setup-cli (como um script de instalação ou GitHub Action): atualize a versão em sua configuração para uma versão corrigida da página de lançamentos da Databricks CLI no GitHub.

  Por exemplo, para usar 0.296.1 com a Ação GitHub:

  - uses: databricks/setup-cli@main
    with:
      version: 0.296.1
  

Erro de credenciais armazenadas

A partir da versão 1.0.0 da CLI do Databricks, os tokens de autenticação U2M (usuário para máquina) passam a ser armazenados no armazenamento seguro nativo do sistema operacional (Chaveiro no macOS, Gerenciador de Credenciais no Windows e Secret Service do D-Bus no Linux), em vez de em um arquivo JSON. Consulte o armazenamento de tokens. Se o fluxo de trabalho se basear no arquivo JSON, ele não funcionará no novo método de armazenamento e você poderá encontrar problemas nos seguintes cenários:

• Atualizado para GA, mas ainda não fez login novamente. A CLI do Databricks não lê mais as credenciais armazenadas por versões mais antigas e retorna um erro:

  Stored credentials from older CLI versions are no longer used.
  Run "databricks auth login" to sign in again.
  
  If secure storage is not available in this environment, set
  DATABRICKS_AUTH_STORAGE=plaintext and re-run login.
  

  Execute databricks auth login para resolver isso.

• A verificação do armazenamento seguro falha ao fazer login Durante databricks auth login, a CLI do Databricks verifica o armazenamento seguro antes de iniciar o fluxo de OAuth. Se a verificação falhar (mais comum em contêineres Linux, sessões SSH, WSL1 e servidores sem interface gráfica em que o D-Bus não estiver em execução), o comportamento depende de o armazenamento seguro ter sido configurado explicitamente:

  • Modo padrão, sem configuração de armazenamento explícita: a CLI do Databricks retorna silenciosamente para texto sem formatação e grava auth_storage = plaintext na [__settings__] seção de ~/.databrickscfg. Os comandos subsequentes usam texto simples sem verificar novamente.
  • Modo de segurança explícito (DATABRICKS_AUTH_STORAGE=secure ou auth_storage = secure no perfil de configuração): a CLI do Databricks retorna um erro apontando para o DATABRICKS_AUTH_STORAGE=plaintext fallback.

  Se a verificação expirar em vez de falhar imediatamente (por exemplo, o chaveiro está bloqueado, mas acessível), a CLI do Databricks mantém o backend do chaveiro, e o prompt de desbloqueio do sistema operacional é exibido em paralelo com o fluxo OAuth no navegador.

  Para confirmar qual modo de armazenamento a CLI do Databricks está usando após o logon, execute databricks auth describe.

• O conjunto de chaves não pode ser acessado ao ler um token armazenado. Ao contrário do logon, a CLI do Databricks não recua silenciosamente quando não consegue alcançar o conjunto de chaves no tempo de leitura do token. Por exemplo, se você fez login em uma máquina desktop e depois se conectou via SSH em uma sessão sem interface gráfica, os comandos que precisam do token armazenado falham e exibem um erro. Use o texto sem formatação como alternativa para resolver isso. Veja Usar a alternativa de texto simples.

Comandos não concluídos

Se você executar um comando como databricks cluster list e ele parecer travado, atualize sua versão da CLI do Databricks para a versão mais recente. Versões anteriores da CLI tentariam carregar listas completas mesmo se o número de itens na lista fosse grande e o comando parecesse não ser concluído.