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 へのワークフローの実行中に、次のエラーが発生します。

これらのエラーを解決するには、BigQuery のエラー メッセージをご覧ください。

includeDependentAssertions プロパティの競合

1 つのファイル内で同じアクションに対して異なる値で 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 は現在のバージョンの @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 URL を生成し、package.json のパッケージ ターゲットを更新します。Dataform でパッケージをインストールする方法 について詳しくは、パッケージをインストールするをご覧ください。

エンドユーザー認証情報の権限が拒否されました

Google アカウントのユーザー認証情報を使用してワークロードを実行したが、Dataform に必要な権限がない場合、次のエラーが発生します。

Dataform does not have the necessary permissions to run your workload using end user credentials. Error details: Account restricted: https://accounts.google.com/info/servicerestricted?...

このエラーは、組織がユーザー ID とコンテキストに基づいてサービスへのアクセスを制限するコンテキストアウェア アクセスのルールを使用している場合に発生する可能性があります。 Google Cloud

このエラーを解決するには、Dataform が Google アカウントのユーザー認証情報を使用できるように、コンテキストアウェア アクセスの構成を更新する必要があります。 これを行うには、アクセスレベル構成で Dataform の OAuth クライアント ID を除外する必要があります。アプリケーションの除外について詳しくは、 サポートされているアプリケーションのアクセスレベルを構成するをご覧ください。

Dataform の OAuth クライアント ID を取得するには、Cloud カスタマーケアにお問い合わせください。

パッケージ インストールのタイムアウト

package.json で定義されたパッケージのサイズが NPM 依存関係の最大サイズを超えると、次のエラーが発生します。

API request error: Package installation timed out

このエラーを解決するには、package.json から冗長なパッケージを削除します。package.json ファイルに @dataform/cli が含まれていないこと、および定義された NPM 依存関係の合計サイズが 200 MB を超えていないことを確認します。

リリース構成が Git コミットを参照している場合は、ターゲットの package.json ファイルが有効であることを確認してください。

サービス アカウントとして動作する権限が拒否されました

厳格な act-as モードが有効になっていて、アクションを実行するプリンシパルに有効なサービス アカウントに対する iam.serviceAccounts.actAs 権限がない場合、次のエラーが発生します。

Permission denied: Principal CALLER_EMAIL is missing 'iam.serviceAccounts.actAs' permission on service account SERVICE_ACCOUNT_EMAIL.

このエラーは、次のアクション中に発生する可能性があります。

  • リポジトリの作成または更新。
  • ワークフロー構成の作成または更新。
  • ワークフロー呼び出しの作成。
  • リリース構成の更新。

このエラーを解決するには、有効なサービス アカウントのプリンシパルに サービス アカウント ユーザー ロール （roles/iam.serviceAccountUser）を付与します。詳細については、 必要な IAM ロールを付与するをご覧ください。

サービス アカウントがプルダウン メニューに表示されない

リポジトリまたはワークフロー呼び出しを構成するときに、[サービス アカウント] メニューに既存のカスタム サービス アカウントが表示されないことがあります。

Dataform は Identity and Access Management API を使用してサービス アカウントを一覧表示します。これには、プロジェクト レベルの iam.serviceAccounts.list 権限が必要です。

この問題を解決するには、以下のいずれかを行います。

  • [手動で入力] をクリックして、サービス アカウント ID を入力します。
  • プロジェクト管理者に、プロジェクトに対する サービス アカウント閲覧者ロール （roles/iam.serviceAccountViewer）または iam.serviceAccounts.list権限を含む別のロールを付与してもらいます。

プライベート パッケージ レジストリにアクセスできない

非公開パッケージの 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 の不安定さや、サードパーティ リポジトリ接続が正しく設定されていない場合、次のエラーが発生します。

Remote repository REPOSITORY_NAME could not be reached.

このエラーを解決するには、サードパーティの Git リポジトリに接続するに記載されている手順をすべて行っていることを確認します。特に、Git リポジトリ ホストに公開インターネットからアクセスできることを確認します。また、認証トークンまたは秘密鍵が正しく、リポジトリにアクセスするために必要な権限があることを確認します。

リモート リポジトリにアクセスできない: 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.

このエラーを解決するには、次の手順を行います。

不明な引数: tags

Dataform CLI のバージョンが tags 引数を認識しない場合、次のエラーが発生します。

Unknown argument: tags

このエラーを解決するには、次の手順を行います。

  • CLI のバージョンを CLI 3.0.0 以降に更新します。本番環境にデプロイする前に、常に非本番環境で新しいパッケージ バージョンをテストしてください。
  • ベスト プラクティスとして、利用可能な最新バージョンの Dataform コア パッケージを常に使用することをおすすめします。
  • package.json でパッケージ バージョンを明示的に指定します（例: 3.0.0）。package.json の他の dependencies オプション （>version など）は使用しないでください。