Troubleshoot the Databricks CLI

Note

Databricks CLI use is subject to the Databricks License and Databricks Privacy Notice, including any Usage Data provisions.

Use the following information to troubleshoot issues with the Databricks CLI.

Enable logging

If a command fails or does not produce the expected output, you can use logging to help identify what might have gone wrong. You can log messages that the Databricks CLI outputs about various command events, warnings, and errors. To log these messages, specify the following Databricks CLI command options:

Flag	Description
--log-file	A string representing the file to write output logs to. If this flag is not specified then the default is to write output logs to stderr.
--log-format	text to write output logs to text or json to write output logs to JSON. If this flag is not specified then output logs are written as text.
--log-level	A string representing the log format level. Valid log levels are error, warn, info, debug, trace, and disabled. The default level is disabled, which means nothing is logged. --debug is equivalent to --log-level debug.

The following example command logs trace messages for the specified command to a file named databricks-cli.log in JSON format.

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

Error downloading Terraform

An expired key in some versions of the Databricks CLI causes the following error when running databricks bundle deploy:

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

To resolve this error, upgrade the Databricks CLI to a latest patched version, which updates the verification mechanism to work with a newer key. Upgrade to the patched version that corresponds to your current CLI minor version:

• Binary install: Download the patched version from the Databricks CLI releases page on GitHub.

• setup-cli (as an install script or GitHub Action): Update the version in your configuration to a patched version from the Databricks CLI releases page on GitHub.

  For example, to use 0.296.1 with the GitHub Action:

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

Stored credentials error

Starting in Databricks CLI version 1.0.0, the Databricks CLI stores user-to-machine (U2M) authentication tokens in OS-native secure storage (keychain on macOS, Credential Manager on Windows, D-Bus Secret Service on Linux) instead of a JSON file. See Token storage. If your workflow builds on top of the JSON file it won't work against the new storage method and you may encounter issues in the following scenarios:

• Upgraded to GA, not yet logged in again. The Databricks CLI no longer reads credentials stored by older versions and returns an error:

  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.
  

  Run databricks auth login to resolve this.

• Secure storage check fails at login During databricks auth login, the Databricks CLI checks the secure storage before starting the OAuth flow. If the check fails (most common in Linux containers, SSH sessions, WSL1, and headless servers where D-Bus is not running), the behavior depends on whether secure storage was explicitly configured:

  • Default mode, no explicit storage setting: the Databricks CLI silently falls back to plaintext and writes auth_storage = plaintext into the [__settings__] section of ~/.databrickscfg. Subsequent commands use plaintext without rechecking.
  • Explicit secure mode (DATABRICKS_AUTH_STORAGE=secure or auth_storage = secure in the configuration profile): the Databricks CLI returns an error pointing to the DATABRICKS_AUTH_STORAGE=plaintext fallback.

  If the check times out instead of failing outright (for example, the keychain is locked but reachable), the Databricks CLI keeps the keychain backend and the OS unlock prompt runs in parallel with the browser OAuth flow.

  To confirm which storage mode the Databricks CLI is using after login, run databricks auth describe.

• Keychain not reachable when reading a stored token. Unlike during login, the Databricks CLI does not silently fall back when it cannot reach the keychain at token read time. For example, if you logged in on a desktop machine and then connected over SSH in a headless session, commands that need the stored token fail with an error. Use the plaintext fallback to resolve this. See Use the plaintext fallback.

Commands not finishing

If you run a command such as databricks cluster list and it appears to hang, update your version of the Databricks CLI to the most recent version. Earlier versions of the CLI would attempt to load complete lists even if the number of items in the list was large, and the command would appear to not finish.