排查 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 工作流调用错误

在将 SQL 工作流执行到 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 核心更新到最新版本。
  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 会自动使用当前版本的 @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 中安装软件包，请参阅安装软件包。

软件包安装超时

如果 package.json 中定义的软件包大小超出 NPM 依赖项的大小上限，则会出现以下错误：

API request error: Package installation timed out

如需解决此错误，请从 package.json 中移除多余的软件包。确保 package.json 文件不包含 @dataform/cli，并且定义的 NPM 依赖项的总大小不超过 200MB。

如果您的版本配置引用了 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 注册表。如需了解详情，请参阅对私密软件包进行身份验证。

无法访问远程仓库

由于 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 问题仍然存在，否则后续的安排发布时间的版本可能会成功发布。

无法访问远程仓库的 Secret

如果您的 Dataform 服务账号无法访问关联的第三方代码库的 Secret Manager Secret，则会出现以下错误：

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。
  • 从 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。