針對 Databricks CLI 進行疑難解答

注意

Databricks CLI 的使用受限於 Databricks 授權 和 Databricks 隱私權注意事項，包括任何使用數據條款。

使用下列資訊來針對 Databricks CLI 的問題進行疑難解答。

啟用 記錄

如果命令失敗或不會產生預期的輸出，您可以使用記錄來協助識別可能發生錯誤的原因。 您可以記錄 Databricks CLI 針對各種命令事件、警告和錯誤所輸出的訊息。 若要記錄這些訊息，請指定下列 Databricks CLI 命令選項：

旗標 描述
--log-file 字串，表示要寫入輸出記錄檔的檔案。 若未指定此旗標，則預設值是將輸出記錄寫入 stderr。
--log-format text 將輸出記錄寫入文字或 json 將輸出記錄寫入 JSON。 若未指定此旗標，則輸出記錄會寫入為文字。
--log-level 表示日誌格式層級的字串。 有效的對數層級為 error、 warn、 infodebugtracedisabled和 。 預設等級是 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 次要版本的已修補版本：

  • Binary 安裝：從 GitHub Databricks CLI releases 頁面下載修補版本。

  • setup-cli（作為安裝腳本或GitHub動作）：將你的設定版本更新為已修補的版本，該版本來自GitHub的 Databricks CLI releases 頁面。

    例如，使用 0.296.1 配合 GitHub 動作：

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

儲存憑證錯誤

從 Databricks CLI 1.0.0 版本開始，Databricks CLI 將使用者對機器（U2M）認證憑證儲存在作業系統原生的安全儲存中（macOS 為 keychain，Windows 為 Credential Manager，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 寫入 ~/.databrickscfg 的 [__settings__] 區段。 後續指令則使用純文字，無需重新檢查。
    • 明確指定安全模式（組態設定檔中為 DATABRICKS_AUTH_STORAGE=secure 或 auth_storage = secure）：Databricks CLI 會傳回錯誤，指出回退至 DATABRICKS_AUTH_STORAGE=plaintext。

    如果檢查逾時而非完全失敗（例如鑰匙圈被鎖定但可達），Databricks CLI 會保留鑰匙圈後端，作業系統解鎖提示則與瀏覽器 OAuth 流程平行執行。

    登入後要確認 Databricks CLI 使用的儲存模式，請執行 databricks auth describe。

  • 讀取儲存的代幣時無法存取鑰匙圈。 不同於登入時，Databricks CLI 在讀取權杖時若無法存取鑰匙圈，不會靜默回退。 舉例來說，如果你在桌上型電腦登入後，透過 SSH 在無頭會話中連線，需要儲存令牌的指令會錯誤失敗。 使用明文備援來解決這個問題。 參見 「使用純文字備援」。

指令未完成

如果您執行像是 databricks cluster list 這樣的命令並且它似乎掛起，請將您的 Databricks CLI 版本更新至最新版本。 舊版的 CLI 會嘗試載入完整清單，即使清單中的專案數目很大，而且指令似乎未完成。

  • Last updated on