Databricks CLI 故障排除

注意

Databricks CLI 使用受 Databricks 许可证和 Databricks 隐私声明的约束，包括任何使用情况数据预配。

使用以下信息排查 Databricks CLI 的问题。

启用日志记录

如果命令失败或未生成预期的输出，可以使用日志记录来帮助确定可能出错的地方。 可以记录 Databricks CLI 输出的有关各种命令事件、警告和错误的日志消息。 若要记录这些消息，请指定以下 Databricks CLI 命令选项：

标记 说明
--log-file 一个字符串，表示要将输出日志写入到的文件。 如果未指定此标志，则默认会将输出日志写入到 stderr。
--log-format 如果设置为 text，则以文本格式写入输出日志；如果设置为 json，则以 JSON 格式写入输出日志。 如果未指定此标志，则以文本格式写入输出日志。
--log-level 一个表示日志格式级别的字符串。 有效的日志级别为 error、、warn、infodebug、 trace和 disabled。 默认级别为 disabled，这意味着不会记录任何内容。 --debug 等效于 --log-level debug。

以下示例命令将指定命令的跟踪消息记录到 JSON 格式命名 databricks-cli.log 的文件。

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

下载 Terraform 时出错

Databricks CLI 的某些版本中的过期密钥在运行时 databricks bundle deploy会导致以下错误：

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

若要解决此错误，请将 Databricks CLI 升级到 最新修补的版本，这会更新验证机制以使用较新的密钥。 升级到与当前 CLI 次要版本相对应的修补版本：

存储凭据错误

从 Databricks CLI 1.0.0 版本开始，Databricks CLI 将用户到机器 (U2M) 身份验证令牌存储在操作系统原生的安全存储中（macOS 上的钥匙串、Windows 上的凭据管理器、Linux 上的 D-Bus Secret Service），而不是存储在 JSON 文件中。 请参阅 令牌存储。 如果工作流基于 JSON 文件生成，则它不适用于新的存储方法，并且可能会遇到以下情况中的问题：

  • 已升级到 GA，但尚未再次登录。 Databricks CLI 不再读取旧版本存储的凭据，并返回错误：

    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.

    运行 databricks auth login 以解决此问题。

  • 登录时安全存储检查失败 在此期间 databricks auth login，Databricks CLI 会在启动 OAuth 流之前检查安全存储。 如果检查失败（Linux 容器、SSH 会话、WSL1 和未运行 D-Bus 的无外设服务器中最常见），则行为取决于是否显式配置了安全存储：

    • 默认模式，没有显式存储设置：Databricks CLI 以无提示方式回退到纯文本并写入 auth_storage = plaintext 到 [__settings__] 部分 ~/.databrickscfg。 后续命令使用纯文本而不重新检查。
    • 显式安全模式（配置文件中的 DATABRICKS_AUTH_STORAGE=secure 或 auth_storage = secure）：Databricks CLI 会返回一条指向 DATABRICKS_AUTH_STORAGE=plaintext 回退的错误信息。

    如果检查超时而不是完全失败（例如，密钥链被锁定但可访问），Databricks CLI 将密钥链后端和 OS 解锁提示与浏览器 OAuth 流并行运行。

    若要确认 Databricks CLI 在登录后正在使用哪个存储模式，请运行 databricks auth describe。

  • 读取存储的令牌时无法访问密钥链。 与登录期间不同，当 Databricks CLI 在令牌读取时无法访问密钥链时，不会以无提示方式回退。 例如，如果在台式计算机上登录，然后在无外设会话中通过 SSH 连接，则需要存储令牌的命令会失败并出现错误。 使用纯文本回退方案来解决这个问题。 请参阅使用纯文本后备方案。

命令未完成

如果运行命令（例如 databricks cluster list）时出现卡顿，请更新您的 Databricks CLI 到最新版本。 即使列表中的项数较大，早期版本的 CLI 也会尝试加载完整列表，并且命令似乎未完成。

  • Last updated on