排解 Dataform 問題

本文說明如何解決 Dataform 的問題。

存取 BigQuery 的要求遭拒

在授予 Dataform BigQuery 存取權之前觸發管道呼叫時，會發生下列錯誤：

Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.

如要解決這項錯誤，請授予 Dataform BigQuery 存取權。

遠端存放區的存取權杖遭拒

如果已連結第三方存放區的驗證權杖無法存取該存放區，就會發生下列錯誤：

The access token for remote repository REPOSITORY_NAME was rejected

如要解決這個錯誤，請檢查 Git 供應商的必要權限，並據此更新 Secret Manager 驗證權杖。如要進一步瞭解如何在 Dataform 中驗證第三方 Git 存放區，請參閱「連線至第三方 Git 存放區」。

已超過 BigQuery 配額

如果 Dataform 傳送至 BigQuery 的 API 要求數量超過 BigQuery 配額，就會發生下列錯誤：

Quota exceeded: Your user_method exceeded quota for concurrent api requests
per user per method.

如要解決這個錯誤，請透過下列方式，將並行查詢數量減少至 250 以下：

• 在 Dataform 中，使用標記分類動作，並一次只執行所選標記。
• 在 Dataform 中，導入動作之間的依附元件。
• 在 Dataform 中，將動作的執行作業劃分到不同Google Cloud 專案。

如要瞭解如何在 BigQuery 中解決這項錯誤，請參閱「排解配額和限制錯誤」。

超出 BigQuery 查詢並行上限

如果同時執行的 BigQuery 查詢數量超出 BigQuery 查詢並行限制，就會發生下列錯誤：

Exceeded rate limits: too many concurrent queries for this project_and_region

如要解決這個錯誤，請透過下列方式，將並行查詢數量減少至 250 以下：

• 在 Dataform 中，使用標記分類動作，並一次只執行所選標記。
• 在 Dataform 中，導入動作之間的依附元件。
• 在 Dataform 中，將動作的執行作業劃分到不同Google Cloud 專案。

如要瞭解如何在 BigQuery 中解決這項錯誤，請參閱「排解配額和限制錯誤」。

BigQuery pipeline 呼叫錯誤

將工作流程執行至 BigQuery 時，會發生下列錯誤：

• 以「BigQuery error messages」(BigQuery 錯誤訊息) 開頭的管道呼叫錯誤。

如要解決這些錯誤，請參閱 BigQuery 錯誤訊息。

相衝突的 includeDependentAssertions 屬性

如果一個檔案中，同一個動作的 includeDependentAssertions 參數設有不同值，編譯期間就會發生下列錯誤：

Conflicting "includeDependentAssertions" properties are not allowed. Dependency
dependencyName has different values set for this property.

如要解決這個錯誤，請編輯檔案並移除重複的 includeDependentAssertions 參數。

如要進一步瞭解如何使用 includeDependentAssertions 參數將斷言設為依附元件，請參閱「將所選動作的斷言設為依附元件」。

編譯失敗

由於編譯的查詢大小或數量，編譯期間發生下列錯誤：

• Compilation timed out. Reduce the complexity of your project to ensure it can compile within limits.
• Compilation exceeded its allowed heap memory limits. Reduce the complexity of your project to ensure it can compile within limits.
• Compilation exceeded its allowed ArrayBuffer or string memory limits. Reduce the complexity of your project to ensure it can compile within limits.

如要解決這些錯誤，請按照下列步驟操作：

1. 將 Dataform 核心更新至最新版本。
2. 檢查工作流程，找出並減少效率不彰之處。
3. 縮減 SQL 查詢的大小。

4. 減少記憶體中的 JavaScript 作業量，例如：

   config { config {type: "table" }}
   js {
       const tooBig = new Uint8Array(110_000_000);
   }
   SELECT ...
   

5. 分割存放區。

如要進一步瞭解 Dataform 編譯資源限制，請參閱配額與限制。

@dataform/core 個依附元件錯誤

如果 package.json 中的 dataform-core 依附元件過時，編譯期間會發生下列錯誤：

Failed to resolve @dataform/core

@dataform/core version should be X.X.X or newer

package.json 中必須有 @dataform/core 依附元件。在存放區中初始化第一個工作區時，Dataform 會自動在 package.json 中填入 @dataform/core 的目前版本。請將 @dataform/core 更新至最新版本。

如要解決這類問題，請將 @dataform/core 更新至最新版本。

無法解決「dataform.json」問題

初始化 Dataform 工作區時，如果初始化程序無法安裝所有套件，就會發生下列錯誤：

Uncaught Error: Failed to resolve dataform.json

如要解決這個錯誤，請在工作區中開啟 package.json，然後按一下「安裝套件」。

無法解決「workflow_settings.yaml」問題

初始化 Dataform 工作區時，如果初始化程序無法安裝所有套件，就會發生下列錯誤：

Uncaught Error: Failed to resolve workflow_settings.yaml

如要解決這項錯誤，請在工作區中開啟 workflow_settings.yaml，然後按一下「安裝套件」。

不支援 git+ 套件目標

在 package.json 中定義套件時，如果目標以 git+ 為前置字元，就會發生下列錯誤：

'git+' prefixed package targets are not currently supported. However,
in most cases they can be used via a '.tar.gz' suffixed target instead.

Dataform 不支援以 git+ 為前置字元的套件目標。

如要解決這個錯誤，請產生套件的 tar.gz 網址，並更新 package.json 中的套件目標。如要進一步瞭解如何在 Dataform 中安裝套件，請參閱「安裝套件」。

套件安裝逾時

如果 package.json 中定義的套件大小超過 NPM 依附元件大小上限，就會發生下列錯誤：

API request error: Package installation timed out

如要解決這項錯誤，請從 package.json 移除多餘的套件。請確認 package.json 檔案不含 @dataform/cli，且定義的 NPM 依附元件總大小不超過 200 MB。

如果您的發布設定參照了 Git 修訂版本，請確認目標位置的 package.json 檔案有效。

無法連線至私人套件登錄檔

私有套件的 Dataform 驗證過期時，會發生下列錯誤：

Permission denied when fetching one or more npm packages. Please verify that
private registry authentication details are valid for each npm registry

如要解決這個錯誤，請確認每個 NPM 登錄檔的私有登錄檔驗證詳細資料都有效。詳情請參閱驗證私人套件。

無法連線至遠端存放區

如果 Git 不穩定，或連結的第三方 Git 存放區中的分支名稱包含非 ASCII 或非英文字元，就會發生下列錯誤：

Remote repository REPOSITORY_NAME could not be reached.

如要解決這項錯誤，請檢查已連結第三方存放區中的分支名稱。如果分支名稱包含非 ASCII 或非英文字元，請刪除該分支。

無法連線至遠端存放區：generic::invalid_argument

如果排定發布的項目偶爾遇到 GitHub、GitLab 或 Bitbucket 連線緩慢、不穩定或中斷的情況，發布設定詳細資料頁面就會顯示下列錯誤：

generic::invalid_argument: Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

您不必採取任何行動。除非 GitHub、GitLab 或 Bitbucket Cloud 發生問題，否則後續排定的發布作業應可順利完成。

無法連線至遠端存放區的密鑰

如果 Dataform 服務帳戶無法存取已連結第三方存放區的 Secret Manager 密鑰，就會發生下列錯誤：

Dataform's service account is unable to reach the configured secret.
Make sure the secret exists and is shared with your Dataform service account:
SERVICE_ACCOUNT_ID.

如要解決這項錯誤，請按照下列步驟操作：

• 確認您的 Dataform 服務帳戶有權存取密鑰。
• 將密鑰從 VPC-SC 服務範圍中排除。Dataform 目前不支援 VPC-SC。

不明引數：tags

如果您的 Dataform CLI 版本無法辨識 tags 引數，就會發生下列錯誤：

Unknown argument: tags

如要解決這項錯誤，請按照下列步驟操作：

• 將 CLI 更新至 3.0.0 以上版本。在正式環境中部署新套件版本前，請務必先在非正式環境中測試。
• 最佳做法是使用最新版本的 Dataform 核心套件。
• 在 package.json 中明確指定套件版本，例如 3.0.0。請勿使用其他 dependencies 選項，例如 package.json 中的 >version。