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` 个媒体资源存在冲突

如果在一个文件中为同一操作设置了具有不同值的 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 组织政策限制条件。如需了解详情，请参阅允许跨项目关联服务账号。
确保调用方主账号对自定义服务账号具有 Service Account User 角色 (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 会自动使用 @dataform/core 的当前版本填充 package.json。您需要将 @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?...

如果您的组织使用情境感知访问权限规则，根据用户身份和情境限制对 Google Cloud 服务的访问，则可能会发生此错误。

如需解决此错误，您可能需要更新情境感知访问权限配置，以允许 Dataform 使用 Google 账号用户凭证。为此，您需要在访问权限级别配置中豁免 Dataform 的 OAuth 客户端 ID。如需详细了解如何豁免应用，请参阅为受支持的应用配置访问权限级别。

如需获取 Dataform 的 OAuth 客户端 ID，请与 Cloud Customer Care 团队联系。

未能解析 `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 依赖项的总大小不超过 200Mb。

如果您的发布配置引用了 Git 提交，请确保其目标位置的 package.json 文件有效。

充当服务账号的权限请求被拒

如果执行操作的主体缺少有效服务账号的 iam.serviceAccounts.actAs 权限，则会发生以下错误：

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

此错误可能会在执行以下操作期间发生：

创建或更新代码库。
创建或更新工作流配置。
创建工作流调用。
更新版本配置。

如需解决此错误，请向有效服务账号的主账号授予 Service Account User 角色 (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：直接在 Git commitish（例如 main 或特定 Git 标记）上调用 CreateCompilationResult 会要求 Dataform 在每次执行时执行全新的 Git 克隆并通过网络安装软件包。在多个流水线中频繁触发 commitish 编译会增加外部网络依赖项和执行延迟时间。
使用版本配置：对于生产执行，请使用版本配置。发布配置会按照受控时间表编译代码库，并保存不可变的编译结果。下游工作流执行会立即使用此缓存结果，而无需查询外部 Git 代码库。
错开预定执行时间：在安排多个编译或发布触发器时，请错开其 cron 计划，以分散网络负载。例如，将时间表错开 5-10 分钟，而不是同时运行所有作业。
在编排工作流中添加重试机制：从外部调度器（例如 Managed Service for Apache Airflow）编排 Dataform 编译时，请在操作器上配置采用指数退避算法的自动重试机制，以妥善应对临时网络不稳定的情况。例如，在 Airflow DAG 中使用 DataformCreateCompilationResultOperator 时，请按以下方式配置重试：

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 资产的代码库。

无法访问远程仓库的 Secret

当 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 服务代理是否有权访问该 Secret。

下拉菜单中未显示服务账号

配置代码库或工作流调用时，服务账号菜单可能不会列出现有的自定义服务账号。

Dataform 使用 Identity and Access Management API 列出服务账号。这需要项目级层的 iam.serviceAccounts.list 权限。

如需解决此问题，请执行以下某项操作：

点击手动输入，然后输入服务账号 ID。
请让您的项目管理员为您授予 View Service Accounts 角色 (roles/iam.serviceAccountViewer) 或包含项目的 iam.serviceAccounts.list 权限的其他角色。

未知参数：tags

如果您的 Dataform CLI 版本无法识别 tags 参数，则会发生以下错误：

Unknown argument: tags