Databricks Git 資料夾故障排除錯誤

本頁說明使用Azure Databricks Git資料夾與遠端Git提供者時常見的錯誤與意外行為，並依類別分組，幫助您更快找出原因。 如果這裡的指引都無法解決你的問題，請參考 「尋求幫助」。

認證錯誤

這些錯誤發生在 Azure Databricks 無法向遠端 Git 提供者驗證你的身份時。

Invalid credentials

嘗試下列作業：

  • 確認 Git 整合設定 （設定>連結帳戶） 正確無誤。 您必須輸入 Git 提供者使用者名稱和令牌。

  • 請確認你在設定>中的連結帳號中選擇了正確的 Git 供應商。

  • 確認你的個人存取權杖或應用程式密碼是否擁有正確的倉庫存取權限。

  • 如果你的 Git 服務提供商啟用了 SSO，請授權你的 token 進行 SSO。

  • 使用 Git 命令列測試您的令牌。 取代角括號中的文字字串：

    git clone https://<username>:<personal-access-token>@github.com/<org>/<repo-name>.git

SSL 連線錯誤

<link>: Secure connection to <link> could not be established because of SSL problems

當 Azure Databricks 無法透過 HTTPS 存取你的 Git 伺服器時，會發生此錯誤。 通常表示您組織 Git 基礎架構存在網路連線問題或 TLS 憑證問題。

在聯絡您的 Azure Databricks 帳戶團隊之前，請先準備好以下資訊：

  • 你的 Git 伺服器網址
  • 無論伺服器使用自簽或私有CA憑證
  • 是否同一工作區的其他使用者會看到相同的錯誤

Microsoft Entra ID 憑證錯誤

Encountered an error with your :re[ms-entra-id] credentials. Try logging out of :re[ms-entra-id] and logging back in.

此錯誤可能發生在您的組織最近啟用多重驗證（MFA）政策時。 當 MFA 強制執行生效時，現有的 Microsoft Entra ID 會話可能無法符合新的認證要求，導致連線失敗。

若要解決此錯誤：

  1. 進入 portal.azure.com，登出 Microsoft Entra ID。
  2. 重新登入。 你應該會看到完成 MFA 的提示。

如果還是不行，請先登出所有 Azure 服務，再重新登入。

儲存庫狀態錯誤

這些錯誤發生在本地 Git 資料夾達到無法正常操作的狀態。

分離的主體狀態

在 Git 中，「head」指的是提交歷史中目前的位置，通常指向分支。 當 HEAD 直接指向特定提交而非分支時，儲存庫會處於「detached HEAD」狀態。 Git 不會追蹤任何分支在此狀態下的變更。 如果你在沒有先建立新分支的情況下直接離開，這些變更可能會遺失。

Git 儲存庫可能會在下列情況下進入分離的 HEAD 狀態：

  • 有人刪除了遠端分支。 Azure Databricks 嘗試透過將未提交的本地變更套用到預設分支來恢復。 如果有相互衝突的變更，Azure Databricks 會在預設分支的快照上套用這些變更，因而產生分離的 HEAD。
  • 使用者或服務主體使用 update repo API 來檢查標籤。

若要從此狀態復原：

  1. 按一下 建立分支，即可從目前提交建立分支，或按一下 選取分支 以切換至現有分支。
  2. 提交並推送以保留您的變更。 要捨棄變更，請點擊 烤肉選單圖示。 在 變更中。

儲存庫狀態不一致

There was a problem with deleting folders. The repo could be in an inconsistent state and re-cloning is recommended.

此錯誤表示刪除資料夾時發生問題。 該資料庫目前處於不穩定狀態。 刪除並重新複製儲存庫以重置其狀態。

筆記本名稱衝突

擁有相同或相似檔名的筆記本在建立儲存庫或拉取請求時可能會出錯：

Cannot perform Git operation due to conflicting names

A folder cannot contain a notebook with the same name as a notebook, file, or folder (excluding file extensions).

即使檔案副檔名不同，也可能發生命名衝突。 例如，這兩個檔案衝突：

  • notebook.ipynb
  • notebook.py

圖表：筆記本、檔案或資料夾的名稱衝突。

要解決衝突，請重新命名導致錯誤狀態的筆記本、檔案或資料夾。 如果在複製倉庫時發生錯誤，請在遠端 Git 倉庫中重新命名筆記本、檔案或資料夾。

意外行為

這些問題不會產生明確的錯誤訊息，但它們是需要調查的問題徵兆。

逾時錯誤

像是複製大型儲存庫或檢查大型分支這類操作，都可能導致逾時錯誤。 逾時後，該作業仍可能在背景中完成。

如果出現逾時錯誤：

  1. 等幾分鐘，然後重新整理 Git 資料夾。 如果存在預期的檔案或分支，則表示該操作已成功完成。
  2. 如果工作區負載過重，負載減少後再嘗試操作。

為了避免大型儲存庫的逾時，建議使用 Sparse checkout ，只處理你需要的檔案。

404 錯誤

如果你打開非筆記本檔案時出現 404 錯誤，請等幾分鐘再試一次。 系統啟用工作區和網頁應用程式接手設定之間會有短暫的延遲。

筆記本在未經使用者編輯的情況下會被修改

如果筆記本的每一行都被修改卻沒有任何使用者編輯，這些變更很可能是因為行尾差異所致。 Azure Databricks 使用 Linux 風格的行尾字元（LF），這可能與在 Windows 系統上提交的檔案所使用的行尾字元（CRLF）不同。

要診斷這個問題，請檢查你是否有以下檔案 .gitattributes ：

  • 它無法容納 * text eol=crlf。
  • 如果你不是用 Windows，請移除這個設定。 你的開發環境和 Azure Databricks 都使用 Linux 的換行符號。
  • 如果你用的是 Windows，請把設定改成 * text=auto。 Git 會在內部以 Linux 風格行尾儲存檔案，但檢出時會自動使用平台特定的行尾符號。

如果你已經在 Git 中提交了包含 Windows 行尾字元的檔案：

  1. 清除任何未完成的變更。
  2. 依照上述描述更新 .gitattributes 檔案以符合你的環境。
  3. 認可變更。
  4. 執行 git add --renormalize。 認可並推送所有變更。

恢復已刪除的檔案

檔案的恢復能力會因行動而異。 有些動作允許透過 垃圾桶 恢復，有些則不行。 若要還原先前已提交並推送到遠端分支的檔案，請使用遠端儲存庫的 Git 提交歷史：

Action 檔案是否可復原？
使用工作區瀏覽器刪除檔案 是，從 [垃圾箱] 資料夾
使用 Git 資料夾對話框捨棄新檔案 是，從 [垃圾箱] 資料夾
使用 Git 資料夾對話框捨棄修改過的檔案 否，檔案已消失
reset （強制）用於尚未提交的檔案修改 否，檔案修改已消失
reset（硬的）針對未提交的新建立檔案 否，檔案修改已消失
使用 [Git 資料夾] 對話框切換分支 是，來自遠端 Git 存放庫
Git 資料夾對話框中的其他 Git 操作，例如提交或推送 是，來自遠端 Git 存放庫
PATCH 使用 Repos API 更新的作業 /repos/id 是，來自遠端 Git 存放庫

尋求幫助

如果本頁的指引都無法解決你的問題，請聯絡 Azure Databricks 客服。 聯絡客服時，請包含以下事項：

  • 錯誤訊息的確切內容
  • 請提供你的 Git 服務提供者名稱，以及該倉庫是公開還是私人
  • 問題是影響所有使用者還是只影響工作空間中的部分使用者
  • 你已經嘗試過的步驟
  • Last updated on