排查 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 属性

如果在编译期间，在一个文件中为同一操作设置了具有不同值的 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 Core 更新到最新 版本。
  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 网址，并更新 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?...

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

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

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

软件包安装超时

如果 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 使用 Identity and Access Management API 列出服务账号。这需要在项目级具有 iam.serviceAccounts.list 权限。

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

  • 点击手动输入 ，然后输入服务帐号 ID。
  • 请项目管理员向您授予 View Service Accounts 角色 (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 问题持续存在，否则后续计划的发布可以成功。

无法访问远程代码库的密文

如果您的自定义服务帐号无法访问已连接第三方代码库的 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 版本更新到 3.0.0 或更高版本。在生产环境中部署之前，请务必先在非生产环境中测试新的软件包版本。
  • 根据最佳实践，请始终使用最新可用的 Dataform Core 软件包版本。
  • 在 package.json 中明确指定软件包版本，例如 3.0.0。请勿使用其他 dependencies选项 的 package.json，例如 >version。