共用方式為

Azure 開發者 CLI 錯誤常見問題解答

本文提供你在使用 Azure Developer CLI（azd）時可能遇到的常見錯誤的解決方案。

角色指派寫入授權失敗

錯誤訊息：The template deployment failed with error: 'Authorization failed for template resource '<guid>' of type 'Microsoft.Authorization/roleAssignments'. The client '##Email##' with object id '<guid>' does not have permission to perform action 'Microsoft.Authorization/roleAssignments/write' at scope '<resourceId>'.'

Cause： 你沒有足夠的權限來指派目標Azure訂閱或資源群組的角色。 這種情況很常見於你的使用者帳號只有Contributor權限，但沒有Owner或User Access Administrator權限。 Contributor 允許你建立資源，但不能授予權限（指派角色）。

解決： 請確保您的帳號在你部署的訂閱或資源群組中擁有 擁有 者或 使用者存取管理員 的角色。 如果無法獲得這些職務，請管理員幫你執行初步部署或角色分配。 更多資訊請參閱 Azure 內建角色。

角色指派已經存在

錯誤訊息：The role assignment already exists.

原因： 此錯誤發生在部署嘗試建立資源上已存在的角色指派時。 雖然 Azure Resource Manager（ARM）部署具有冪等性，但在重新部署時，模板中的某些配置或競爭條件可能會觸發此錯誤。

解決： 這種錯誤通常是間歇性的或良性的。

  1. 重試部署： 執行 azd up 或 azd deploy，然後再執行一次。
  2. 檢查Bicep模板： 若你維護模板，請確保角色指派使用有效的 name 屬性（通常為嚴格確定性的 GUID）以確保冪性。 使用 guid（） Bicep 函式來產生確定性名稱。

租戶編號、委託人識別碼或範圍不允許更新

錯誤訊息：Tenant ID, application ID, principal ID, and scope are not allowed to be updated.

原因： 你正在嘗試重新部署一個角色分配，其屬性與現有分配不同。 角色分配是不可變的;你無法更改主體 ID（接收角色的使用者/應用程式）或現有指派 ID 的範圍。

解決方法：

  1. 驗證參數： 確保你不會不小心傳遞不同的主體 ID（例如在用戶和服務主體之間切換），針對相同的角色指派資源。
  2. 清理： 如果您需要更改指派，請在 Azure 入口網站 或使用 CLI 執行 az role assignment delete 手動刪除衝突的角色指派，然後再重新部署。

區域容量或 SKU 不可用

錯誤訊息：The region 'eastus2' currently does not have enough resources available to provision services with the SKU 'standard'. （或稱「基本」）

原因： 所選Azure區域暫時無法承載所需服務 SKU。 目前，在熱門地區（如 eastus2）使用的 AI 服務（例如 Azure OpenAI）相當常見。

解決方法：

  1. 更換地點：跑到azd env set AZURE_LOCATION <new-region>可用性較好的區域切換（例如 swedencentral， ， westus3francecentral）。
  2. Check availability： 使用 Azure 產品依區域頁面，或執行 az account list-locations 查詢該服務與 SKU 可用的區域。

TPM AI 模型的配額已超出限制

錯誤訊息：This operation require <amount> new capacity in quota Tokens Per Minute (thousands) - <model> - GlobalStandard, which is bigger than the current available capacity <available>.

Cause： 您的訂閱已達到目標區域指定Azure OpenAI 模型的每分鐘代幣數（TPM）配額上限。

解決方法：

  1. Request Quota： 透過 Azure AI Studio 或 Azure 入口網站申請配額增加。 欲了解更多資訊，請參閱管理Azure OpenAI Service配額。
  2. 更換模型/地區： 切換到你有空配額的區域，或使用符合你限制的其他型號。

If-Match 先決條件失敗

錯誤訊息：The specified precondition 'If-Match = ""&lt;guid&gt;""' failed.

原因： 此問題通常表示並行衝突。 兩個程序可能同時嘗試更新同一個資源，或者你的本地狀態與雲端資源不同步（ETag 過時）。

解決： 重試手術。 如果錯誤仍然存在：

  1. 確保沒有其他的部署（如 CI/CD 流水線或其他同事）正在同時針對同一個環境。
  2. 如果使用 Bicep，請確認你的範本正確定義了相依關係（dependsOn），以防止對同一資源進行平行修改。

認知服務帳戶狀態為已接受

錯誤訊息：Call to Microsoft.CognitiveServices/accounts failed. Error message: Account <resourceId> in state Accepted.

Cause： 此錯誤是時序問題，當依賴資源試圖與認知服務（Azure AI）帳號互動時，尚未完全配置並啟用。 你也可以在azure.yaml裡加入一個命令掛鉤 （例如 postprovision），讓它在繼續前暫停或檢查資源是否準備好。

容器應用程式修訂條款已過期

錯誤訊息：Failed to provision revision for container app <appName>. Error details: Operation expired.

Cause： Azure容器應用程式未能在預設逾時期內啟動。 常見原因包括：

  • 容器圖片太大，拉取時間太長。
  • 應用程式啟動時會當機。
  • 應用程式在監聽設定的埠口時花費的時間過長。

解決方法：

  1. Check Logs： 在Azure入口網站（Log Stream）或使用 azd monitor 查看容器日誌，看看應用程式是否當機。
  2. 檢查設定： 確保你的設定中的 targetPort 與應用程式監聽的端口一致。 更多故障排除步驟，請參見 Troubleshooting Azure Container Apps
  3. Check Logs： 在Azure入口網站（Log Stream）或使用 azd monitor 查看容器日誌，看看應用程式是否當機。
  4. 檢查配置： 確保你的設定與應用程式監聽的 targetPort 埠口相符。
  5. 優化影像： 縮小容器圖片大小以加快拉取速度。
  • Last updated on