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 プロパティ

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. 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 は 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 URL を生成し、package.json のパッケージ ターゲットを更新します。Dataform にパッケージをインストールする方法については、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 レジストリで有効であることを確認します。詳細については、Dataform で非公開パッケージを認証するをご覧ください。

リモート リポジトリにアクセスできない

次のエラーは、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 など）は使用しないでください。