排查问题

本文档列出了 Data Agent Kit IDE 扩展程序捕获并显示的可见错误。这些错误通常以 IDE 中的通知（弹出式窗口）或状态栏警告的形式显示。请使用本指南来发现和解决问题。

如果您在查看此处列出的可能错误后仍无法确定问题的来源，请尝试退出账号并重新登录。

身份验证和 gcloud CLI 错误

这些错误会影响扩展程序的基本连接。

错误消息

可能的原因

补救措施

Google Cloud CLI is required... but was not found.

gcloud 二进制文件不在系统路径中。

安装 Google Cloud CLI 并重启 IDE。

You must be logged in to both the Google Cloud CLI and ADC...

尚未运行 gcloud auth login 或 gcloud auth application-default login。

点击状态栏或通知，以在终端中触发登录流程。

状态栏中您的账号名称旁边会显示 $(warning) 图标。

登录的扩展程序账号与活跃的 gcloud CLI 账号不同。

使用登录 Google Cloud时所用的同一账号运行 gcloud auth login 和 gcloud auth application-default login。

状态栏显示 $(warning) 图标。

扩展程序设置（例如项目 ID、区域或结算项目 ID）与 gcloud CLI 设置不一致。

点击项目状态栏中的警告图标，以在扩展程序和 gcloud CLI 之间同步设置。或者，手动更新任一工具中的配置，以确保它们一致。

Cannot sync settings: gcloud CLI or ADC account does not match extension account。

尝试在账号不一致时同步设置。

使 gcloud CLI 和扩展程序之间的账号保持一致。确保他们使用的是同一用户账号、项目、区域和结算项目。

Cannot sync settings: Google Cloud CLI is not installed.

尝试在未安装 gcloud CLI 的情况下同步设置。

安装 gcloud CLI。

Explorer 和 API 提取错误

以下是在 Google Cloud 数据代理工具包菜单树中浏览云资源时遇到的常见错误。

错误消息

可能的原因

补救措施

Failed to load ${itemKind}: ${error.message}

服务器无法授权您的请求（HTTP 403 Forbidden 状态代码）、服务器找不到资源（HTTP 404 Not Found 状态代码），或者 API 未启用。

验证 Identity and Access Management (IAM) 权限；确保在设置中启用相关 API（例如 BigQuery）。

No Google Cloud project selected.

在没有有效项目的情况下触发了某项功能。

使用状态栏中的项目选择器选择项目。

Invalid table name format: ${tableName}

命名惯例不正确（缺少项目 ID 或数据集 ID）。

使用完全限定名称：project.dataset.table。

BigQuery 和 Dataform 错误

以下错误专门针对 SQL 转换和 Dataform 项目管理。

错误消息

可能的原因

补救措施

Dataform CLI is not installed. Dataform features will not work.

Dataform npm 软件包未全局安装。

点击对话框中的 Install Dataform CLI 以自动执行安装。

Failed to compile project in folder...: ${stderr}

.sqlx 文件中存在语法错误或 workflow_settings.yaml 无效。

在 Dataform Compiled Query 视图中查看具体的语法错误。

Failed to run Dataform project: ${message}

BigQuery 作业执行失败。

查看 BigQuery 作业历史记录，了解详细的执行日志。

No content found for saved query: ${label}

Knowledge Catalog 或 BigQuery 条目存在，但包含 NoSQL 内容。

在 Google Cloud 控制台中运行查询，验证查询内容。

Managed Service for Apache Spark 和 Spark 错误

以下错误与集群管理和 Spark 执行相关。

错误消息

可能的原因

补救措施

Error starting/stopping/restarting cluster ${name}: ${message}

IAM 权限不足或集群处于过渡状态。

确保您拥有 roles/dataproc.editor 角色；检查集群状态是否已为 UPDATING。

Error: No cluster name found.

树状视图中的内部引用错误。

刷新 Spark 资源浏览器视图。

Failed to redirect to Spark UI: ${message}

集群已停止或组件网关已停用。

启动集群，并确保在集群配置中启用了组件网关。

Failed to load [clusters/jobs/sessions/session templates]: [message]

API 错误

刷新 Spark 资源浏览器视图。

Failed to start Jupyter process / Pip install failed.

本地 Jupyter 服务器启动失败或所需软件包的安装失败。

打开一个使用远程内核的新 Spark 笔记本。

No sample notebooks found for the selected kernel type.

没有适用于所选内核类型（本地或远程）的示例笔记本。

不适用

This system does not have Windows Long Path support enabled. Please enable long paths and restart your IDE to work with Spark Notebooks on remote kernels. Learn More

此问题专门针对 Windows 用户，当您的机器上未启用长路径时，可能会出现此问题。

请参阅通知中的链接，以启用长路径。

google-cloud-jupyter-config and jupyter_server are required to connect to remote kernels on Managed Service for Apache Spark. Install them?

当用户首次尝试使用远程内核时，系统会显示此消息。

点击通知，然后在确认对话框中选择是，以安装依赖项。

Requires package installation

如果缺少 Jupyter 依赖项，则显示在内核选择器中远程内核旁边的说明中。

点击通知，然后在确认对话框中选择是，以安装依赖项。

Install dependencies for remote Spark kernels. Require google-cloud-jupyter-config and jupyter_server

当用户在远程内核上运行现有笔记本时，显示在内核选择器说明中

点击通知，然后在确认对话框中选择是，以安装依赖项。

Cloud Storage 错误

在管理存储桶和对象时，系统会显示以下错误。

错误消息

可能的原因

补救措施

A folder with the name... already exists.

存储桶中的命名冲突。

选择一个唯一的文件夹名称。

Upload/Download failed: ${message}

权限被拒或网络超时。

验证 Storage Object Admin 或 Creator 角色。

Failed to create bucket: ${message}

名称已被全局使用或包含无效字符。

遵循 Cloud Storage 存储桶命名规则。

一般接口错误

这些错误表明出现了界面级故障。

错误消息

可能的原因

补救措施

No workspace folder open.

用户在 IDE 中处于 No Folder 模式。

使用 File > Open Folder 打开文件夹。

No active notebook editor found.

您正在运行 Spark 或 SQL 命令，但未打开笔记本。

打开 .ipynb 或 .sql 文件。

Cannot insert item: unsupported resource type.

尝试拖放具有 NoSQL 字符串表示形式的资源。

只有表、视图和列可以插入到编辑器中。

数据库错误

查询 Google Cloud 数据库时会返回以下错误。

AlloyDB

错误消息

可能的原因

补救措施

postgresql error: role "[USER_EMAIL]" does not exist

登录扩展程序的用户尚未添加为实例的 IAM 用户。

如需将用户添加为 IAM 用户，请参阅管理 IAM 身份验证。

postgresql error: permission denied for table [TABLE_NAME]

IAM 用户无权访问相应对象。

如需向 IAM 用户授予对象的权限，请参阅向 IAM 用户授予适当的数据库权限。

Cloud SQL for MySQL

错误消息 可能的原因 补救措施
Invalid request: Some of your SQL statements failed to execute. Details: Error 1045 (28000): Access denied for user '[USER]'@'localhost' (using password: YES).
  • 对于 IAM 数据库身份验证：登录到扩展程序的用户尚未作为 IAM 用户添加到实例中。
  • 对于内置数据库身份验证：Secret Manager 中所选的区域 Secret 或 Secret 版本与数据库用户的密码不匹配。
Invalid request: Some of your SQL statements failed to execute. Details: Error 1044 (42000): Access denied for user '[USER]'@'%' to database '[DB_NAME]'. 数据库用户无权访问数据库。 请参阅向单个 IAM 用户或服务账号授予数据库权限或配置数据库用户以授予数据库权限。
Invalid request: Failed to access secret '[SECRET_VERSION]': generic::PERMISSION_DENIED: Permission 'secretmanager.versions.access' denied for resource '[SECRET_VERSION]' (or it may not exist). 登录到扩展程序的账号无权访问 Secret Manager 中的区域级密钥版本，或者该密钥版本不存在。 验证查询设置中选择的区域 Secret 和 Secret 版本是否存在。然后，向您的账号授予 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。请参阅 Cloud SQL Data API 文档中的所需角色或权限。
Invalid request: Secret fetched from Secret Manager is empty 所选的区域 Secret 版本不包含密码。 添加包含数据库用户密码的新密文版本，然后在查询设置中选择该版本。
Invalid request: The instance doesn't allow using ExecuteSql to access this instance. You can allow it by patching the instance with {settings: { dataApiAccess: "ALLOW_DATA_API" }} 未启用 Data API 访问权限。 通过查询设置启用 Data API 访问权限，或参阅使用 Cloud SQL Data API 执行 SQL 语句，以通过 Google Cloud 控制台或 gcloud CLI 启用该权限。
Invalid request: IAM authentication is not enabled for the instance [PROJECT_ID]:[INSTANCE_NAME] IAM 身份验证标志未启用。 通过查询设置启用 IAM 身份验证标志，或参阅 IAM 身份验证，了解如何通过 Google Cloud 控制台或 gcloud CLI 启用该标志。

Cloud SQL for PostgreSQL

错误消息 可能的原因 补救措施
Invalid request: The instance doesn't allow using ExecuteSql to access this instance. You can allow it by patching the instance with {settings: { dataApiAccess: "ALLOW_DATA_API" }} 未启用 Data API 访问权限。 通过查询设置启用 Data API 访问权限，或参阅使用 Cloud SQL Data API 执行 SQL 语句，以通过 Google Cloud 控制台或 gcloud CLI 启用该权限。
Invalid request: IAM authentication is not enabled for the instance [PROJECT_ID]:[INSTANCE_NAME] IAM 身份验证标志未启用。 通过查询设置启用 IAM 身份验证标志，或参阅 IAM 身份验证，了解如何通过 Google Cloud 控制台或 gcloud CLI 启用该标志。
Invalid request: Some of your SQL statements failed to execute. Details: pq: password authentication failed for user "[USER]".
  • 对于 IAM 数据库身份验证：登录到扩展程序的用户尚未作为 IAM 用户添加到实例中。
  • 对于内置数据库身份验证：Secret Manager 中所选的区域 Secret 或 Secret 版本与数据库用户的密码不匹配。
Invalid request: Failed to access secret '[SECRET_VERSION]': generic::PERMISSION_DENIED: Permission 'secretmanager.versions.access' denied for resource '[SECRET_VERSION]' (or it may not exist). 登录到扩展程序的账号无权访问 Secret Manager 中的区域级密钥版本，或者该密钥版本不存在。 验证查询设置中选择的区域 Secret 和 Secret 版本是否存在。然后，向您的账号授予 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。请参阅 Cloud SQL Data API 文档中的所需角色或权限。
Invalid request: Secret fetched from Secret Manager is empty 所选的区域 Secret 版本不包含密码。 添加包含数据库用户密码的新密文版本，然后在查询设置中选择该版本。
Execution failed. All statements are aborted. Details: pq: permission denied for table [TABLE_NAME] 数据库用户无权访问相应对象。 如需授予数据库权限，请参阅使用 IAM 数据库身份验证管理用户或配置数据库用户。

Spanner

错误消息

可能的原因

补救措施

Result set too large. Result sets larger than 10.00M can only be yielded through the streaming API.

不支持结果大小超过 10.00 MiB 的查询。

请参阅 executeSql。

后续步骤