Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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 リポジトリに接続するをご覧ください。

Secure Source Manager 接続に Developer Connect プロキシがない

プロキシが有効になっていない Developer Connect 接続を使用して Dataform リポジトリを Secure Source Manager（プレビュー）リポジトリにリンクすると、次のエラーが発生します。

This repository uses a Secure Source Manager connection that does not have the Developer Connect proxy enabled. Dataform cannot access it. Select a different repository, or link a new repository using a connection with the proxy enabled.

このエラーを解決するには、別のリポジトリを選択するか、プロキシが有効になっている接続を使用して新しいリポジトリをリンクするか、既存の Developer Connect 接続を更新してプロキシを有効にします。詳細については、Developer Connect を使用してリモートリポジトリを接続するをご覧ください。

BigQuery クエリの同時実行数の上限超過

BigQuery に対して実行される同時実行クエリの数が BigQuery クエリの同時実行数の上限を超えると、次のエラーが発生します。

Exceeded rate limits: too many concurrent queries for this project_and_region

このエラーを解決するには、次の方法で並列クエリの数を 250 未満に減らします。

Dataform では、タグを使用してアクションを分類し、一度に選択したタグのみを実行します。
Dataform で、アクション間の依存関係を導入します。
Dataform では、アクションの実行を異なるGoogle Cloud プロジェクト間で分割します。

BigQuery でこのエラーを解決する手順については、割り当てと上限のエラーのトラブルシューティングをご覧ください。

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 のエラーメッセージで始まるパイプライン呼び出しエラー。

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

コンパイルの失敗

コンパイルされたクエリのサイズまたは数が原因で、コンパイル中に次のエラーが発生します。

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.
Compilation cancelled because it exceeded size limits.

これらのエラーを解決する手順は次のとおりです。

Dataform コアを最新バージョンに更新します。
ワークフローを検査して、非効率な部分を特定して削減します。
SQL クエリのサイズを小さくする。
メモリ内の JavaScript オペレーションの量を減らします。次に例を示します。
```
config { config {type: "table" }}
js {
    const tooBig = new Uint8Array(110_000_000);
}
SELECT ...
```
リポジトリを分割する。

Dataform コンパイルリソースの上限の詳細については、割り当てと上限をご覧ください。

`includeDependentAssertions` プロパティの競合

1 つのファイル内で同じアクションに異なる値の includeDependentAssertions パラメータが設定されている場合、コンパイル中に次のエラーが発生します。

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

このエラーを解決するには、ファイルを編集して、includeDependentAssertions パラメータの競合する繰り返しを削除します。

includeDependentAssertions パラメータを使用してアサーションを依存関係として設定する方法については、選択したアクションのアサーションを依存関係として設定するをご覧ください。

プロジェクト間のサービスアカウントの関連付けがブロックされる

Dataform リポジトリとは異なるプロジェクトのカスタムサービスアカウントを使用しようとしたときに、組織のポリシーの制約によってオペレーションがブロックされると、次のエラーが発生します。

The caller does not have permission to act as service account: SERVICE_ACCOUNT_EMAIL

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

カスタムサービスアカウントが配置されている Google Cloud プロジェクトを特定します。
そのプロジェクトで、iam.disableCrossProjectServiceAccountUsage 組織のポリシーの制約を無効にします。詳細については、プロジェクト間でサービスアカウントの接続を有効にするをご覧ください。
呼び出し元プリンシパルに、カスタムサービスアカウントに対するサービスアカウントユーザーロール（roles/iam.serviceAccountUser）が付与されていることを確認します。

詳細については、プロジェクト間のサービスアカウントの接続を処理するをご覧ください。

`@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 を最新バージョンに更新します。

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

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 カスタマーケアにお問い合わせください。

`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 でのパッケージのインストールの詳細については、パッケージをインストールするをご覧ください。

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

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

API request error: Package installation timed out

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

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

サービスアカウントとして機能するための権限が拒否されました

アクションを実行するプリンシパルに、有効なサービスアカウントに対する 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 認証が期限切れになると、次のエラーが発生します。

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 リポジトリに接続できない場合、次のいずれかのエラーが発生します。

Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Error during remote operation: SSH connection to remote repository 'REMOTE_REPOSITORY_URL' timed out.

Error during remote operation: `Read timed out`.

Error during remote operation: `Connection time out`.

Error during remote operation: The remote repository 'REMOTE_REPOSITORY_URL' closed connection during remote operation.

これらの接続エラーを解決する方法は、障害が永続的か一時的かによって異なります。

永続的な接続エラー

コンパイルの試行ごと、または初期リポジトリの設定中にエラーが常に発生する場合は、接続エラーが永続的です。接続が正しく構成されていないか、認証情報の有効期限が切れています。このエラーを解決する手順は次のとおりです。

Git リポジトリホストが公共のインターネットからアクセス可能であることを確認します。
リモートの Git リポジトリに公共のインターネット経由でアクセスできない場合は、Developer Connect を使用して Dataform から安全に接続します。
認証トークンまたは SSH 認証鍵が有効で、期限切れになっておらず、リポジトリにアクセスできることを確認します。
サードパーティの Git リポジトリに接続するの手順をすべて実施します。

一時的または断続的な接続エラー

スケジュールされた実行中や、複数のワークフローが同時にトリガーされたときにエラーが散発的に発生する場合は、接続エラーは一時的なものです。リモートリポジトリへの外部ネットワーク接続が一時的に不安定になっている可能性があります。

本番環境の信頼性を最適化し、一時的な接続エラーを防ぐには、次のベストプラクティスに沿って対応してください。

本番環境で commitish のコンパイルを頻繁に行わない: main や特定の Git タグなどの Git commitish で CreateCompilationResult を直接呼び出すと、Dataform は実行ごとに新しい Git クローンを実行し、ネットワーク経由でパッケージをインストールする必要があります。複数のパイプラインで commitish のコンパイルを頻繁にトリガーすると、外部ネットワークへの依存度が高まり、実行レイテンシが増加します。
リリース構成を使用する: 本番環境での実行には、リリース構成を使用します。リリース構成は、制御されたスケジュールでリポジトリをコンパイルし、不変のコンパイル結果を保存します。ダウンストリームワークフローの実行では、外部 Git リポジトリにクエリを実行することなく、このキャッシュに保存された結果がすぐに使用されます。
スケジュールされた実行を分散する: 複数のコンパイルまたはリリーストリガーをスケジュールする場合は、cron スケジュールを分散してネットワーク負荷を分散します。たとえば、すべてのジョブを同時に実行するのではなく、スケジュールを 5 ～ 10 分ずらします。
オーケストレーションワークフローに再試行を追加する: Managed Service for Apache Airflow などの外部スケジューラから Dataform コンパイルをオーケストレートする場合は、オペレーターに指数バックオフを使用した自動再試行を構成して、一時的なネットワークの不安定さに適切に対処します。たとえば、DataformCreateCompilationResultOperator を使用する Airflow DAG で、次のように再試行を構成します。

from datetime import timedelta
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
)

create_compilation_result = DataformCreateCompilationResultOperator(
    task_id="create_compilation_result",
    project_id="PROJECT_ID",
    region="REGION",
    repository_id="REPOSITORY_ID",
    compilation_result={
        "git_commitish": "GIT_COMMITISH",
    },
    retries=5,
    retry_delay=timedelta(minutes=2),
    retry_exponential_backoff=True,
)

Dataform にリポジトリが表示されない

一部の Dataform リポジトリは、Cloud Asset Inventory の検索や IAM 権限の監査に表示されることがありますが、 Google Cloud コンソールの Dataform には表示されません。

ラベルを使用してこれらのリポジトリの送信元を特定する方法については、BigQuery アセットのリポジトリを特定するをご覧ください。

リモートリポジトリのシークレットにアクセスできない

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 サービスエージェントにシークレットへのアクセス権があることを確認します。

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

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

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

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

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

不明な引数: tags

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

Unknown argument: tags

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

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

Dataform のトラブルシューティング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

BigQuery へのアクセス拒否

リモート リポジトリのアクセス トークン拒否

Secure Source Manager 接続に Developer Connect プロキシがない

BigQuery クエリの同時実行数の上限超過

BigQuery の割り当て超過

BigQuery パイプライン呼び出しエラー

コンパイルの失敗

includeDependentAssertions プロパティの競合

プロジェクト間のサービス アカウントの関連付けがブロックされる

@dataform/core 件の依存関係エラー

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

dataform.json の解決失敗

workflow_settings.yaml の解決失敗

git+ パッケージ ターゲットがサポートされていない

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

サービス アカウントとして機能するための権限が拒否されました

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

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