這個錯誤目錄可協助您排解及解決佈建 Apigee 資源時可能發生的常見錯誤。並提供詳細資訊，說明在佈建期間，UI 或指令列可能傳回的錯誤。
目錄包含下列資訊：
- 錯誤代碼
- 錯誤訊息
- 錯誤的可能原因
- 解決錯誤的步驟
佈建期間傳回的錯誤
無論是透過 Cloud 控制台的 Apigee UI 或指令列介面 (CLI) 佈建 Apigee 資源，系統都會在佈建期間發出 API 呼叫。在佈建期間或檢查佈建狀態時發出的 API 呼叫，可能會在各種情況下傳回錯誤，包括：
- 專案未啟用 Google Cloud 帳單功能
- 專案未啟用必要的 API
- 區域、對等互連範圍或其他網路設定問題
一般來說，錯誤訊息會提供相關資訊，協助您修正問題、解決錯誤，並解除佈建封鎖。
錯誤格式
如果錯誤是這個目錄中列出的常見錯誤，Cloud 控制台的 Apigee UI 中會顯示錯誤訊息。例如：
{
"error": {
"code": "FAILED_PRECONDITION",
"message": "Error finding one or more network address ranges to use for the Instance. Verify
the network configuration provided for the Instance and try again."
}
}請使用提供的訊息搜尋這份參考資料，進一步瞭解錯誤的可能原因，以及解決問題的潛在步驟。
常見錯誤
該地點的可用資源不足
錯誤訊息
location "[loc]" does not have enough resources available to fulfill the request. Try again later or choose a different location
可能原因
如果要求在可用區或區域中佈建 Apigee 執行個體，但該可用區或區域缺少一或多個資源，就可能發生這項錯誤。這項錯誤並非執行個體設定有問題所致。
解決步驟
如要解決這項錯誤，您可以選擇在其他區域佈建執行個體，或等待問題解決 (通常會在幾小時內解決)。
服務網路驗證失敗
錯誤訊息
您會看到初始網路驗證錯誤訊息，之後可能還會看到下列一或多則詳細錯誤訊息：
generic::failed_precondition: validation failed for service networking for network "[network]", COMPUTE_API_NOT_ENABLED generic::failed_precondition: validation failed for service networking for network "[network]", RANGES_DELETED_LATER generic::internal: error validating service networking consumer config for network "[network]": This API method requires billing to be enabled. Please enable billing on project [project] by visiting ... then retry.
可能原因
如果網路設定的預先佈建驗證失敗，就可能發生這個錯誤。
解決步驟
下表列出可解決這些錯誤訊息的動作：
| 訊息 | 解決步驟 |
| COMPUTE_API_NOT_ENABLED | 啟用 Compute Engine API。 |
| RANGES_DELETED_LATER | 確認提供的 IP 範圍有效。 |
| 必須啟用計費功能 ... | 確認專案已啟用計費功能。 |
找不到 /22 的可用 IP 空間
錯誤訊息
couldn't find a free IP space of /22 to launch an instance. Verify the peering ranges are available as per https://cloud.google.com/apigee/docs/api-platform/get-started/install-cli#service-networking and try again
可能原因
如果在提供的範圍內沒有 /22 的 IP 空間，建立子網路時可能會發生這個錯誤。
解決步驟
如要解決這個錯誤，請確認提供的 IP 對等互連範圍 符合在服務網路中建立子網路的規定。然後重試作業。
分配 IP 時發生錯誤
錯誤訊息
您可能會看到下列其中一則錯誤訊息：
Error in allocating IPs to use for the Instance. Please verify the network configuration provided for the Instance and try again. Error in allocating IPs for ServiceAttachment. Error finding one or more network address ranges to use for the Instance. Verify the network configuration provided for the Instance and try again.
您也可能會收到網路用戶端的詳細錯誤訊息。例如：
Invalid resource usage: 'The resource 'projects/xxx' is already linked to another shared VPC host 'projects/yyy'.
可能原因
執行服務網路作業 (例如建立子網路或搜尋網路範圍) 時，可能會在建立 Apigee 執行個體期間發生這項錯誤。在某些情況下， Service Networking 可能會傳回錯誤訊息。
解決步驟
請按照 Service Networking 傳送的詳細訊息中的指示操作，解決錯誤。您可能需要：
- 更新執行個體提供的 IP 範圍分配。
- 解決其他 Service Networking 設定問題。
- 為執行個體設定使用其他虛擬私有雲網路。
KMS 金鑰權限遭拒
錯誤訊息
apigee service agent <email> cannot encrypt/decrypt with kms key <keyID>: PermissionDenied
可能原因
在佈建 Apigee 執行個體之前，系統會驗證提供的 KMS 金鑰。這個錯誤表示 Apigee 服務代理人沒有正確的權限，無法在提供的金鑰上擔任 Cloud KMS CryptoKey 加密者/解密者角色。
解決步驟
授予 Apigee 服務代理人所提供 KMS 金鑰的存取權。如要瞭解如何授予存取權，請參閱「透過指令列佈建付費機構」一文的步驟 1(f)。
機構政策禁止提出要求
錯誤訊息
The request is prohibited by organization's policy. Please refer to https://cloud.google.com/vpc-service-controls/docs/troubleshooter to review the org policy for VPC Service Control. vpcServiceControlsUniqueIdentifier: <vpc-sc unique identifier>.
可能原因
佈建 Apigee 執行個體時，可能會發生這項錯誤。Google Cloud 機構的 VPC Service Control 政策禁止建立執行個體。
解決步驟
如要解決這項錯誤，請按照「
Communicate, debug, and resolve VPC Service Controls issues with minimal effort」一文中的步驟操作。這些步驟會使用 vpcServiceControlsUniqueIdentifier 修正 VPC-SC 設定。
已達對等互連數量上限
錯誤訊息
The maximum number of peerings for the network (7) has been reached. Please delete unused peerings for the network and try again
可能原因
佈建 Apigee 執行個體時，可能會發生這項錯誤。在本例中，沒有可用的網路對等互連。
解決步驟
如要解決這個錯誤，請刪除網路中所有未使用的對等互連，或為執行個體使用其他 VPC 網路。
超過允許的路由器數量上限
錯誤訊息
exceeded maximum allowed routers in same network and region. Please use a different network + same region OR same network + different region
可能原因
建立 Cloud NAT (網路位址轉譯) 時，可能會在佈建期間發生這個錯誤。在這種情況下，所選網路和區域無效。
解決步驟
如要修正這項錯誤，請在相同區域中選取其他網路，或在不同區域中使用相同網路。
資源無效
錯誤訊息
the resource 'projects/.../regions/.../serviceAttachments/...' was invalid. Must be either a valid In-Project Forwarding Rule Target URL, a valid Service Attachment URL, or a supported Google API bundle (global-only)
可能原因
如果提供的服務附件網址無效，就可能發生這個錯誤。
解決步驟
如要解決這個問題，請將執行個體設定中的服務附件網址更新為有效網址。
找不到資源
錯誤訊息
the resource 'projects/.../regions/.../serviceAttachments/...' was not found
可能原因
如果系統找不到您提供的服務附件 URL，就可能發生這個錯誤。
解決步驟
如要解決這項錯誤，請將例項設定中的服務附件網址更新為有效網址。
網路範圍已刪除，但仍處於指派狀態
錯誤訊息
a network range was deleted but still assigned in network <network>. Please refer to this guide to fix: https://cloud.google.com/sdk/gcloud/reference/services/vpc-peerings/update. Valid ranges can be found at VPC networks -> Private service connection -> Allocated IP ranges for services
可能原因
如果為 Apigee 執行個體分配的網路範圍遭到刪除、部分刪除或不存在，就可能發生這個錯誤。
解決步驟
如要解決這項錯誤，請執行下列指令， 更新已分配範圍的 VPC 對等互連：
gcloud services vpc-peerings update \ --service=servicenetworking.googleapis.com \ --ranges=$VALID_RANGES \ --network=$NETWORK \ --project=$PROJECT \ --force
IP 範圍重疊
錯誤訊息
An IP range in the peer network (10.128.0.0/28) overlaps with an IP range (10.128.0.0/20) in an active peer (peering-to-consumer) of the local network. Please use a different ipRange. If you've recently deleted an ApigeeInstance and wanted to use the same ipRange, please wait for some time and try again
可能原因
佈建 Apigee 執行個體時，可能會發生這項錯誤。在本例中，由於分配的 IP 範圍無效，或是先前建立的 Apigee 執行個體刪除後，分配的範圍尚未完全釋出，因此 Apigee 執行個體建立作業會失敗。
解決步驟
如要解決這項錯誤，請使用其他 IP 範圍，或稍後再試，使用完全釋出的 IP 範圍。
無法連線至私人 Google API 範圍
錯誤訊息
couldn't connect to the private Google APIs ranges. This is likely a DNS mis-configuration if you've set up peered-dns-domains. Please check https://cloud.google.com/vpc/docs/configure-private-google-access#config-domain
可能原因
佈建 Apigee 執行個體時，可能會發生這項錯誤。在這種情況下，Apigee 執行個體無法連線至私人 Google API 範圍。
解決步驟
如要解決這個問題，請確認私人 Google API 範圍的 DNS 設定正確無誤，且可從虛擬私有雲網路內連上私人 Google API 範圍。
已觸發專案刪除作業
錯誤訊息
deletion had been triggered for project <project>
可能原因
如果用於建立執行個體的專案已開始刪除程序，就可能會發生這項錯誤。這項驗證檢查會在佈建作業的每個步驟之間執行。
解決步驟
如果不小心刪除了專案，或許可以使用下列指令還原專案：
gcloud projects undelete PROJECT_ID
詳情請參閱「還原專案」。
KMS 金鑰引數無效
錯誤訊息
apigee service agent <p4sa email> cannot encrypt/decrypt with kms key <kms key>: Invalid Argument
可能原因
佈建期間驗證提供的 KMS 金鑰時，可能會發生這項錯誤。在此情況下，Cloud KMS 金鑰欄位中的一或多個值無效。
解決步驟
如要解決這項錯誤，請確認 Cloud KMS 金鑰的值是否正確，並更新執行個體設定中的欄位。
未啟用 Google Cloud KMS API
錯誤訊息
Google Cloud KMS API has not been used in project <project> before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview?project=<project> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.
可能原因
如果用於 Apigee 佈建的專案未啟用 Cloud KMS API，就可能發生這項錯誤。
解決步驟
如要解決這項錯誤，請啟用 Cloud KMS API。
未啟用 Apigee API
錯誤訊息
Apigee API has not been used in project <project> before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/apigee.googleapis.com/overview?project=<project> then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.
可能原因
如果用於 Apigee 佈建的專案未啟用 Apigee API，就可能會發生這個錯誤。
解決步驟
如要解決這項錯誤，請啟用 Apigee API。
未啟用 Google Cloud 帳單
錯誤訊息
This API method requires billing to be enabled. Please enable billing on project <project number> by visiting https://console.developers.google.com/billing/enable?project=<project number> then retry. If you enabled billing for this project recently, wait a few minutes for the action to propagate to our systems and retry.
可能原因
如果用於 Apigee 佈建的 Google Cloud 專案未啟用帳單功能，就可能發生這個錯誤。
解決步驟
如要解決此錯誤，請為 Google Cloud 專案啟用計費功能。
再次建立服務網路連線
錯誤訊息
please create Service Networking connection with service 'servicenetworking.googleapis.com' from consumer project <project number> network <network> again
可能原因
如果在擷取 Service Networking 主專案號碼時，Google Cloud 專案中的 Service Networking 連線失敗，就可能發生這個錯誤。
解決步驟
如要解決這個問題，請按照步驟 2：設定網路中的說明，建立 Service Networking 連線。
遭拒的 IAM 權限
錯誤訊息
IAM permission denied for service account service-<project number>@gcp-sa-apigee.iam.gserviceaccount.com. Ensure that Apigee service account has Apigee service agent role to your consumer project.
可能原因
如果嘗試與 Google Cloud 消費者專案互動的 Apigee 服務帳戶 IAM 權限不正確，就可能發生這個錯誤。
解決步驟
如要解決這個問題，請將 Apigee service agent 角色指派給啟動這項作業的服務帳戶。您可以在 Google Cloud 主控台的 IAM 頁面中授予權限。