排解 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 以下：

如需在 BigQuery 中解決這項錯誤的操作說明，請參閱「排解配額和限制錯誤」。

已超出 BigQuery 查詢並行處理限制

當向 BigQuery 執行的並行查詢數量超過 BigQuery 查詢並行處理限制時，系統會發生以下錯誤：

Exceeded rate limits: too many concurrent queries for this project_and_region

如要解決這項錯誤，請按照下列方式將並行查詢的數量減少至 250 以下：

如需在 BigQuery 中解決這項錯誤的操作說明，請參閱「排解配額和限制錯誤」。

BigQuery 管道叫用錯誤

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

如要解決這些錯誤，請參閱 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. 檢查 SQL 工作流程，找出並減少效率不彰的部分。
  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 會自動使用目前的 @dataform/core 版本填入 package.json。您需要將 @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。請勿使用 package.json 的其他 dependencies 選項，例如 >version。