跳转至

Troubleshooting（故障排除）

This page addresses common issues and questions that arise when using Pilot.

Seed data and live data

Pilot uses two data sources depending on the view:

  • Editor view always uses seed data generated inside the Pilot container. AI agents never access real enterprise data. This prevents Pilot from hard-coding production values into your application code.
  • Deploy view connects your application to real ontology data. On a deployment branch, ontology schema changes (object types, action types, link types) are scoped to the branch and do not affect Main until you merge. On Main, any actions you perform in the application are live ontology edits that take immediate effect.

Permission errors during deployment

Deployment requires permissions at the project, organization, and enrollment levels. If you encounter permission errors, verify the following:

  • You have at least the Editor role on the Foundry project where Pilot is deploying.
  • You have the Third-party application administrator role in Control Panel, which is required to create the Developer Console application and its linked OAuth client.
  • An enrollment administrator has approved the subdomain request in Control Panel > Approvals.
  • The project does not have marking restrictions that block dataset creation.

For a full breakdown of Developer Console permissions, see Developer Console permissions. If permissions appear correct but errors persist, check the browser console for detailed error messages and share them with your administrator.

Access Pilot logs

To access Pilot system logs:

  1. Select the three-dot menu (...) next to the tab bar in the content header.
  2. Select Pilot logs.

The Pilot Logs tab displays real-time container logs. Use these logs to diagnose build errors, dependency installation issues, and runtime problems.

Build errors in the Preview tab

If the Preview tab shows a build error instead of your application:

  1. Read the error message in the Preview tab. Common errors include missing imports, type mismatches, and syntax errors.
  2. Select Fix with Pilot to prompt Pilot to diagnose and resolve the issue automatically.
  3. If the automatic fix does not resolve the issue, describe the error in the chat panel and ask Pilot to investigate.

You can also check the Pilot logs tab for detailed build output from the development server.

Container startup issues

After you create a new application, Pilot provisions a container. This process typically takes 30 to 60 seconds. Check the following if the container does not start:

  1. Check the status monitoring popover by selecting the status indicator in the top-right corner. The Pilot status field indicates whether the connection is healthy.
  2. If the status shows Disconnected, try refreshing the page.
  3. If the container still does not start after refreshing, create a new Pilot application in a fresh session.

Unintended edits in deploy view

When previewing your application in deploy view on Main, any actions you perform, such as creating, editing, or deleting objects, are live ontology edits that take immediate effect on production data. This is expected behavior, not a bug.

If you want to test actions without affecting production, preview your application in deploy view on a deployment branch instead. Ontology edits made on a branch are scoped to that branch and do not propagate to Main until you merge.

Action references break across environments

When you deploy ontology entities from a Pilot branch to Main, action type identifiers (RIDs) may differ between the branch and Main. This can cause reference errors if your application code references branch-specific RIDs.

To resolve this issue:

  1. After merging your branch, switch back to Main in Pilot when prompted.
  2. If errors persist, ask Pilot to update action references to use the Main branch identifiers.

Divider element console errors

You may see error messages in the browser console referencing "divider" elements with no height. These errors are cosmetic and do not affect application functionality. You can safely ignore them.

Dependency installation failures

Try the following steps if the status monitoring popover shows that npm dependencies failed to install:

  1. Select Fix with Pilot in the status popover to attempt automatic resolution.
  2. If the issue persists, check the Pilot logs tab for specific error messages.
  3. Ask Pilot to reinstall dependencies by typing Reinstall npm dependencies in the chat panel.

Application does not deploy

Follow the steps below if the deployment panel shows that your application is not deployable:

  1. Open the status monitoring popover and check the Deployability status for details.
  2. Common causes include invalid ontology entities, missing required properties, or unresolved build errors.
  3. Select Fix with Pilot to resolve blocking issues automatically.
  4. After fixing issues, retry the deployment from the deployment panel.

中文翻译

故障排除

本页面介绍了使用 Pilot 时常见的 issues（问题）和 questions（疑问）。

种子数据与实时数据

Pilot 根据视图不同使用两种数据源：

  • 编辑器视图始终使用 Pilot 容器内部生成的 seed data（种子数据）。AI 代理永远不会访问真实的企业数据。这可以防止 Pilot 将生产环境的值硬编码到您的应用程序代码中。
  • 部署视图将您的应用程序连接到真实的 ontology data（本体数据）。在部署分支上，ontology schema（本体模式）的变更（对象类型、操作类型、链接类型）仅限于该分支，在您合并之前不会影响 Main 主分支。在 Main 主分支上，您在应用程序中执行的任何操作都是实时的 ontology（本体）编辑，会立即生效。

部署期间的权限错误

部署需要项目、组织和注册级别的权限。如果您遇到 permission errors（权限错误），请验证以下内容：

  • 您至少拥有 Pilot 正在部署的 Foundry 项目的 Editor（编辑者）角色。
  • 您在 Control Panel（控制面板）中拥有 Third-party application administrator（第三方应用程序管理员）角色，这是创建 Developer Console（开发者控制台）应用程序及其关联的 OAuth 客户端所必需的。
  • 注册管理员已在 Control Panel（控制面板）> Approvals（审批）中批准子域名请求。
  • 该项目没有阻止创建数据集的标记限制。

有关 Developer Console（开发者控制台）权限的完整说明，请参阅 Developer Console permissions。如果权限看起来正确但错误仍然存在，请检查浏览器控制台以获取详细的错误消息，并将其分享给您的管理员。

访问 Pilot 日志

要访问 Pilot system logs（系统日志）：

  1. 选择内容标题中标签栏旁边的三点菜单 (...)。
  2. 选择 Pilot logs（Pilot 日志）。

Pilot 日志选项卡会显示实时的容器日志。使用这些日志来诊断构建错误、依赖项安装问题和运行时问题。

预览选项卡中的构建错误

如果 Preview（预览）选项卡显示构建错误而不是您的应用程序：

  1. 阅读 Preview（预览）选项卡中的错误消息。常见错误包括缺少导入、类型不匹配和语法错误。
  2. 选择 Fix with Pilot（使用 Pilot 修复）以提示 Pilot 自动诊断并解决问题。
  3. 如果自动修复无法解决问题，请在聊天面板中描述该错误，并要求 Pilot 进行调查。

您也可以查看 Pilot logs（Pilot 日志）选项卡，以获取来自开发服务器的详细构建输出。

容器启动问题

创建新应用程序后，Pilot 会配置一个容器。此过程通常需要 30 到 60 秒。如果容器未启动，请检查以下内容：

  1. 通过选择右上角的状态指示器来检查状态监控弹出窗口。Pilot status（Pilot 状态）字段指示连接是否正常。
  2. 如果状态显示 Disconnected（已断开连接），请尝试刷新页面。
  3. 如果刷新后容器仍未启动，请在新的会话中创建一个新的 Pilot 应用程序。

部署视图中的意外编辑

在 Main 主分支上以部署视图预览应用程序时，您执行的任何操作（例如创建、编辑或删除对象）都是实时的 ontology（本体）编辑，会立即对生产数据生效。这是预期行为，而非错误。

如果您想在不影响生产环境的情况下测试操作，请在部署分支上以部署视图预览您的应用程序。在分支上进行的 ontology（本体）编辑仅限于该分支，在您合并之前不会传播到 Main 主分支。

跨环境的操作引用中断

当您将 ontology（本体）实体从 Pilot 分支部署到 Main 主分支时，action type（操作类型）标识符（RID）在分支和 Main 主分支之间可能不同。如果您的应用程序代码引用了特定于分支的 RID，这可能会导致 reference errors（引用错误）。

要解决此问题：

  1. 合并分支后，在收到提示时切换回 Pilot 中的 Main 主分支。
  2. 如果错误仍然存在，请要求 Pilot 更新操作引用以使用 Main 主分支的标识符。

分隔符元素控制台错误

您可能会在浏览器控制台中看到引用无高度的 "divider"（分隔符）元素的错误消息。这些错误是表面性的，不会影响应用程序功能。您可以安全地忽略它们。

依赖项安装失败

如果状态监控弹出窗口显示 npm 依赖项安装失败，请尝试以下步骤：

  1. 在状态弹出窗口中选择 Fix with Pilot（使用 Pilot 修复）以尝试自动解决。
  2. 如果问题仍然存在，请检查 Pilot logs（Pilot 日志）选项卡以获取具体的错误消息。
  3. 通过在聊天面板中输入 Reinstall npm dependencies（重新安装 npm 依赖项）来要求 Pilot 重新安装依赖项。

应用程序无法部署

如果部署面板显示您的应用程序无法部署，请按照以下步骤操作：

  1. 打开状态监控弹出窗口，并检查 Deployability（可部署性）状态以获取详细信息。
  2. 常见原因包括无效的 ontology（本体）实体、缺少必需的属性或未解决的构建错误。
  3. 选择 Fix with Pilot（使用 Pilot 修复）以自动解决阻塞问题。
  4. 修复问题后，从部署面板重试部署。