跳转至

故障排查与异常定位 (Troubleshooting)

本指南系统汇总了创作者在使用 Griptape Nodes 过程中最常遭遇的各类报错状态、诱发成因以及精准恢复方案。如果你遇到的故障未在此列出，请查阅常见问题答疑 (FAQ)，或通过 FAQ 底部的官方社区渠道联系我们寻求技术支持。

图像或视频无法在编辑器中显示

典型故障表现

  • Load Image、Save Image 或媒体预览节点在画布上呈现一片空白区域，无法加载图像内容；
  • 目标媒体文件确凿存在于本地磁盘（例如位于 {outputs}/images/...），但编辑器画布无法渲染；

  • 在编辑器中上传新图片失败，终端或前端抛出类似以下报错：

    Error: CreateStaticFileUploadUrl Failed
Description: Failed to create presigned URL for file ...: Client error
'404 Not Found' for url 'http://localhost:8124/static-upload-urls'

核心诱发根因

编辑器画布中的所有多媒体资源，均由计算引擎在本地端口 8124 启动的静态文件服务器 (Static File Server) 进行托管和分发。如果该端口已被占用 —— 最常见的原因是后台仍残留运行着第二个（或先前失联的孤儿）Griptape Nodes 引擎进程 —— 新拉起的引擎静态服务便会被迫退避并随机选用操作系统动态分配的其他空闲端口。

此时，媒体加载请求便会在两个引擎之间发生割裂：失联的孤儿引擎继续霸占着默认的 8124 端口，而你当前实际操作的新引擎却在非标准端口上监听，导致前端画布无法加载预览，并频繁触发 404 上传异常。

恢复与解决步骤

  1. 首先尝试在编辑器界面按下键盘快捷键强制刷新：Windows/Linux 按 Ctrl+R，macOS 按 Cmd+R。这能快速消除因前端临时缓存引起的渲染白屏；
  2. 如果媒体依然无法呈现，请确保整台计算机上仅运行着单一引擎进程。彻底退出 Griptape Nodes，然后排查并终结残留的后台孤儿进程：
    • Windows：打开“任务管理器”，在“进程”列表中查找并强制结束所有残留的 Python 进程；
    • macOS / Linux：打开终端执行 pgrep -fl griptape（或排查由 python 驱动的引擎进程），将其全部杀死（kill）；
  3. 如果无法准确定位或终结残留进程，最简单有效的方式是直接重启计算机。重启能彻底释放被旧进程锁死绑定的所有端口；
  4. 重新启动 Griptape Nodes。在纯净的单进程环境下，多媒体资产即可恢复正常渲染与预览。

排错关键建议

在重启机器后，重新打开工作流之前，请先确认后台绝对只有单一引擎实例在运行。每次软件热更新后残留的僵尸引擎进程，是诱发此故障最普遍的罪魁祸首。

计算引擎运行在远程服务器上？

如果你的 Engine 引擎运行在与浏览器不同的远程工作站（或处于反向代理、内网穿透隧道之后），缺失媒体预览是完全正常的预期现象。你需要显式将编辑器指向正确的服务器地址：请按照静态文件服务器配置指南配置 static_server_base_url。

导入的图片或视频文件大小显示为 0 字节 (0 bytes)

典型故障表现

  • 导入项目工程的图像与视频保存在本地 {inputs}/images/ 或 {inputs}/videos/ 路径下，文件大小恒为 0 bytes（文件资源管理器中显示为 0 KB）；
  • 画布中完全不渲染任何媒体，关闭并重新加载工作流后内容依然丢失；
  • 退出并重启 Griptape Nodes 应用程序无济于事。

核心诱发根因

将文件导入项目工程在底层分为两阶段进行：第一阶段，引擎首先在目标磁盘路径创建一个同名的空白文件完成“占位锁定”；第二阶段，前端编辑器向引擎运行在 8124 端口上的本地静态服务器分片传输实际二进制载荷。当第二阶段发生中断或传输未能成功触发时，磁盘上就仅会留下初始占位的空文件。

经深入底层排查，该故障源于操作系统层面的底层 WebBrowser 管道偶发通信挂起，主要集中出现在 Windows 10 平台上。单纯重启桌面端应用程序无法恢复。

恢复与解决步骤

  • 直接重启计算机。仅重启 Griptape Nodes 软件本体不足以重置底层网络套接字栈。

报错 "Address already in use" / 引擎拒绝启动

典型故障表现

引擎拉起时抛出如下崩溃堆栈：

The 'websocket_direct' driver could not start: its address is already in use.
Another Griptape Nodes engine is probably already running.
Stop the other engine (or change this driver's port) and try again.

核心诱发根因

另一个 Griptape Nodes 引擎进程已经在当前系统中处于运行状态，并独占占用了当前引擎所需的底层通信端口。

恢复与解决步骤

  1. 终结先前的引擎进程。关闭所有 Griptape Nodes 窗口，并参考上文图像媒体异常章节中的指令排查并杀死后台残留的孤儿进程；
  2. 如果你的业务需求确实需要在单台物理机上同时并行运行多个独立引擎，请参阅下文的单机多引擎并行配置方案。

在单台计算机上并行运行多个引擎实例

典型故障表现

当在同一台机器上强行拉起两个或更多引擎时，会出现大量看似诡异且毫无关联的混乱异常：某个引擎错误地响应了发给另一个引擎的请求（甚至同一请求被两个引擎重复执行两次）、两个编辑器会话之间的工作流与运行状态发生严重串号、编辑器误将两个物理引擎识别为同一个实体、频繁出现上述的端口占用报错或媒体无法加载的 404 故障。

核心诱发根因

这是由于两个独立的底层冲突叠加导致的：

  • 引擎身份冲突 (Shared identity)：在未显式注入 GTN_ENGINE_ID 环境变量时，当前机器拉起的所有引擎实例均会使用系统硬编码的全局默认引擎标识符。共用相同身份的引擎会监听完全相同的请求队列，并共享完全相同的会话上下文，导致两者争抢响应发给对方的指令，进而引发雪崩式的逻辑混乱。
  • 端口绑定冲突 (Port conflicts)：第一个拉起的引擎会霸占系统的标准默认端口（例如静态服务器的 8124 端口）；后拉起的引擎被迫退避到动态端口，导致所有默认指向标准端口的外部链路发生断连。

恢复与解决步骤

为每一个额外拉起的引擎实例分配独立的唯一身份 ID 与专属监听端口：

GTN_ENGINE_ID=second-engine STATIC_SERVER_PORT=9000 GTN_MCP_SERVER_PORT=9928 gtn engine

如果你无意并行运行多个引擎，请排查并关闭冗余进程。

报错 "No sessions available" —— 商业许可证用户无法拉起引擎

典型故障表现

企业团队成员使用集中发放的商业许可证密钥（License Key）激活软件，引擎启动进行许可证鉴权核销时抛出错误：No sessions available。

核心诱发根因

企业组织所采购的商业许可证包含固定数量的并发席位池 (License Session Pool)。席位从引擎拉起启动时被占用，直到引擎正常退出关机时才会被安全平滑释放。抛出 No sessions available 意味着席位池中的所有配额已被占满 —— 可能是由于全部成员正在正常使用，也可能是由于死锁僵尸会话 (Stale Session) 导致的：当某个用户的引擎异常崩溃、被任务管理器暴力强制结束、或断网后仍在后台脱机运行时，云端授权中心仍会认为该席位处于存活锁定状态（直到超时心跳自然失效）。

恢复与解决步骤

  1. 首先排查本机是否存在先前异常崩溃残留的孤儿引擎进程（参考上文步骤终结它），正常终止进程会自动向授权中心发送席位释放信号；
  2. 如果席位依然处于死锁占用状态，企业组织管理员可登录企业管理控制台 (Admin Dashboard)，打开 Sessions 弹窗，手动点击 Release 强制释放对应的僵尸会话，即刻腾出席位；
  3. 否则，等待僵尸会话自然超时失效 —— 当不再收到心跳续期请求时，云端席位会在几分钟后自动过期解冻。

报错 No session pool configured？

如果系统抛出的是 No session pool configured，说明你的企业组织尚未完成商业许可证会话池的初始化配置 —— 请直接联系企业内负责 Griptape Nodes 采购的系统管理员。

编辑器画布黑屏或呈现全白无响应

典型故障表现

编辑器窗口瞬间变为纯黑屏或纯白界面，该现象通常在计算机长时间处于休眠唤醒后，或经历短暂的网络断开重连后发生。

恢复与解决步骤

  • 在编辑器中使用深度硬刷新：Windows/Linux 按 Ctrl+Shift+R，macOS 按 Cmd+Shift+R。强制硬刷新会彻底清空前端内存堆栈，并重新与后端计算引擎建立 WebSocket 长连接。

节点库缺失、算子消失或串线报出其他引擎的错误

典型故障表现

  • 节点侧边栏中没有展示任何可用节点库，或预期的核心节点（例如 Agent 智能体节点）无故消失；
  • 编辑器控制台弹出的报错信息，所指代的引擎标识或工作流名称与你当前正在操作的工程完全不符。

核心诱发根因

通常源自以下几种可能：

  • 节点库加载过程受阻中断：当某个自定义库在导入时遭遇致命故障（例如底层 Python 依赖缺失、节点源码文件存在语法错误或导入异常），该节点库包含的所有算子将被静默丢弃。此时，引擎的底层日志是唯一的真相来源。必须导出或查阅引擎日志，定位服务拉起时输出的精确异常堆栈；
  • 配置项“注册节点库清单”与预期脱节：引擎仅会加载明确声明在 Libraries To Register 列表中的节点库（位于 Configuration Editor $\rightarrow$ Libraries $\rightarrow$ Library Registration，底层对应 griptape_nodes_config.json 中的 app_events.on_app_initialization_complete.libraries_to_register 字段）。如果目标库不在清单内、被手动拨至关闭状态，或配置路径已经失效，其节点自然不会展示；
  • 当前前端编辑器实际连接到了另一台远程工作站的引擎上，进而呈现了该远程引擎上的状态与报错。

恢复与解决步骤

  1. 优先排查日志：查看引擎启动加载节点库时打印的详细日志。日志中会准确标注报错的库名及具体崩溃根因。详见下文导出引擎运行日志；
  2. 确认当前编辑器所连引擎的物理来源，避免跨机器多环境误连；
  3. 打开编辑器的 Configuration Editor（配置编辑器），切换到 Libraries 视图，仔细检查 Library Registration $\rightarrow$ Libraries To Register。如果预期的库处于关闭状态或路径失效，重新修正配置，或通过 Manage $\rightarrow$ Library Management $\rightarrow$ Add Library 重新注册绑定。详见节点库开关与移除指南；
  4. 打开 Libraries 面板，将顶部筛选器切换为 Errors，排查未能成功安装或加载失败的异常库。详见库已安装但看不到节点排查指引；
  5. 保持节点库版本处于最新：进入 Manage $\rightarrow$ Library Management，展开对应的节点库，点击 Check for Updates，有可用版本时点击 Update。若需更新引擎本体，请参阅 FAQ。

报错 "failed to locate pyvenv.cfg" / 引擎崩溃无法拉起

典型故障表现

在命令行尝试启动引擎时，控制台抛出致命异常并退出：

failed to locate pyvenv.cfg: The system cannot find the file specified.

核心诱发根因

先前的反安装或更新操作未能完整结束，导致 Griptape Nodes 底层绑定的 Python 虚拟环境处于残缺破损状态。

恢复与解决步骤

  1. 重新执行反安装指令以彻底清除损坏的虚拟环境：

    griptape-nodes self uninstall

    由于虚拟环境已经破损，griptape-nodes 本身可能也会因环境缺失而无法拉起。如果执行卸载时同样报此错误，请按照彻底卸载指南中的说明，通过命令行手动删除配置与虚拟环境文件夹；

  2. 按照安装部署指引重新安装全新纯净的引擎。

报错 "Attempted to create a Flow with a parent 'None'"（通常无害）

典型故障表现

在加载或编排构建工作流画布时，控制台偶发弹出警告：

Attempted to create a Flow with a parent 'None', but no parent with that name could be found.

核心诱发根因

这是一个已知的前端画布拓扑图初始化偶发告警。在绝大多数实际业务场景中，它是完全无害的良性提示，不会对工作流的求值与计算执行造成任何实质性影响。

恢复与解决步骤

  1. 在多数情况下直接忽略该提示，继续推进正常创作即可；
  2. 如果该提示阻塞了界面操作，重启计算引擎即可消除；
  3. 如果你在特定的操作步骤下稳定重现此提示，欢迎向我们提交 Issue 缺陷报告，附上触发该现象的操作上下文以协助我们持续完善系统。

报错 "ssl.SSLCertVerificationError" / 引擎拒绝运行

典型故障表现

启动 Griptape Nodes 时，控制台弹出如下 SSL 证书校验崩溃：

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1000)

核心诱发根因

宿主机操作系统上当前安装的 Python 环境缺失根受信任 SSL 证书链，导致 Python 无法发起任何基于 HTTPS 的加密安全连接。

恢复与解决步骤

  1. 前往 python.org 官方下载页 重新下载安装官方 Python 安装包（Griptape Nodes 要求运行在 Python 3.12 环境）；
  2. 在安装向导末尾，务必勾选并执行 Install Certificates（安装系统证书链）；
    • 若在 macOS 上安装后依然报错，在终端中直接运行官方证书注入脚本：/Applications/Python\ 3.12/Install\ Certificates.command。

导出引擎运行日志与全量诊断包 (Exporting Engine Logs)

在向官方反馈缺陷或自行排查复杂底层错误时，计算引擎的运行日志通常是第一道核心排查线索。然而单纯的几行日志往往很难还原案发现场 —— 当时动态加载了哪些外部库、生效的底层配置参数是什么、相关的模型凭据是否注入到位，均对故障定位至关重要。使用官方提供的系统全量诊断包 (Diagnostics Bundle)，即可一键自动化将上述所有关键证据打包归档。

命令行一键生成全量诊断包

系统诊断包 (Diagnostics Bundle) 是一个高压缩率的 .zip 归档包，内部结构完整规范：

诊断包内部文件 包含的核心关键技术线索
logs/*.log 本地磁盘留存的引擎轮转物理日志文件（按时间由新到旧排列，最顶层覆盖打包时的当前会话）
logs/session.log 引擎仅存在于内存中的最新会话实时日志（仅在磁盘未配置日志写入时生成）
report.json 包含运行的引擎版本、操作系统硬件架构、生效的完整配置项，以及每个项目和节点库的加载状态报告
doctor.json 运行 doctor 深度健康巡检的结果：精准标注潜在隐患及针对性修复建议
workflow/ 当前画布中最后一次保存的工作流拓扑定义文件（仅在由前端编辑器触发生成诊断包时包含）
manifest.json 上述文件的全局校验索引，并附带出于安全考量所自动脱敏的内容总数清单
README.md 面向技术工程师的诊断包全局内容解读说明书

在终端中执行以下命令即可一键捕获：

gtn diagnostics collect

通过上述 CLI 命令生成的诊断包内部不包含 workflow/ 文件夹（因为该命令在后台独立启动了一个临时审查引擎，其未打开任何具体工作流画布）。如果你需要一并将当前出现异常的工作流拓扑结构纳入诊断包，请直接在图形化编辑器界面中生成。

该命令默认在当前终端目录下生成名为 griptape-nodes-diagnostics-<version>-<timestamp>.zip 的归档文件。你也可以通过 --output 指定生成路径（例如直接保存至桌面）：

gtn diagnostics collect --output ~/Desktop

你只需将该压缩包直接附在 GitHub Issue 缺陷报告中即可。该操作绝对不会向任何外部公网自动上传数据 —— 诊断包仅在本地生成，是否分享以及分享给谁完全由你自主掌控。

隐私安全脱敏机制与分享前核对提示

诊断包由本地引擎负责打包生成。引擎由于知悉自身加载的 API Key，因此会自动扫描并过滤所有收集的文件，对所有识别出的 API Key、长 Token 以及密码形态的机密进行强制清除；当前用户主目录统一重写为 ~，真实系统用户名重写为 <user>（如果你希望保留真实路径以排查绝对路径问题，可追加 --show-identity 参数）。所有被脱敏的内容均会被统一标记为 <redacted>，并在 manifest.json 中清晰记录总数。

但需要特别注意的是：对于任何未遵循通用凭证模式的隐蔽机密（例如直接打在文本节点输入框中的明文密码、或某个第三方扩展库以非标准私有格式打入自身日志的私有 Token），自动脱敏系统可能无法做到 100% 盲测识别。在将诊断包公开发布到开源 Issue 等公共讨论区之前，强烈建议先打开压缩包内的 logs/ 目录以及工作流文件粗略审查一番。

如果你仅仅希望在终端中快速查看系统健康状况，无需导出归档文件，可直接运行深度体检命令：

gtn doctor

控制台会即时打印出一张规整的系统体检诊断表，并针对每一项潜在隐患给出针对性的修复建议。

从桌面端应用程序界面导出日志

桌面应用程序为其纳管的本地引擎维护着独立的持久化日志文件，并且支持根据时间范围 (Time Range) 定向切片导出，而不仅局限于当前会话。当系统故障发生于数小时前、或历经了多次引擎重启时，这种定向切片提取尤为高效实用：

  1. 点击桌面应用顶部导航栏中的 Engine 状态按钮，展开引擎快捷弹窗；
  2. 在 Managed Engine 区域下方，点击 Logs 唤起引擎运行日志窗口；
  3. 点击窗口中的 Export 按钮；
  4. 在弹出的 Export Logs 对话框中进行选择：
    • Current Engine Session —— 导出自当前引擎最近一次拉起至今的完整日志；
    • Time Range —— 定向导出指定时间区间内的日志切片，可灵活指定 From 开始时间以及 To 结束时间（或直接勾选 Now）。在故障刚刚重现后，定向导出最近 30 分钟的日志往往比导出全量历史文件更加干净聚焦；
  5. 选择保存路径，将其导出为标准的 .txt 文本文件。

日志导出权限提示

导出日志功能依赖桌面端 应用设置 (App Settings) 中的 Write engine logs to file 配置开关。该选项默认保持开启；若界面中的 Export 按钮呈灰色置灰状态，请点击旁边的 Manage 超链接快捷跳转开启该选项。

从命令行终端实时查阅与捕获日志

如果你是通过命令行终端手动拉起引擎（运行 gtn 或 gtn engine），引擎的实时运行日志将直接源源不断输出到当前控制台中。你可以直接在终端中回滚翻阅并拷贝所需的异常堆栈片段。

此外，计算引擎本身会在后台自动落盘物理日志文件。每个引擎进程会在系统标准数据目录 <XDG_DATA_HOME>/griptape_nodes/logs 下写入日志文件，单文件达到 10 MB 时自动进行滚动切分，并自动清理超过 7 天未被修改的历史旧文件。该行为由以下三个底层配置项统一治理：logging.log_to_file、logging.log_directory 以及 logging.log_retention_days（详见系统底层配置手册）。上文介绍的 gtn diagnostics collect 命令会自动归档捕获这些物理文件。

若默认的运行日志粒度过粗、不足以定位深度代码隐患，你可以随时提升日志详细等级：进入配置编辑器（Settings $\rightarrow$ All Settings），检索 "log level"，将其调整为 DEBUG 级别，然后再次复现故障以捕获深度追踪堆栈（详见在编辑器中修改配置）。在无图形界面的无头（Headless）运行环境下，可以直接通过环境变量在启动时强制指定：

GTN_CONFIG_LOG_LEVEL=DEBUG gtn

内存日志缓冲区保护机制

计算引擎会在物理内存中始终驻留最新的 5,000 行实时日志。因此，即使你的系统全局禁用了向磁盘写入日志文件，在故障发生后立即执行诊断包打包，依然能通过内存捕获这部分现场证据（存为 logs/session.log）。而当磁盘写入正常开启时，打包工具会自动采用包含更长历史周期的物理日志文件。无论采用何种形式，日志输出粒度均受当时设置的 Log Level 控制，因此在排查复杂疑难杂症前，建议提前将日志级别切换至 DEBUG。你可以通过 logging.session_log_buffer_lines 自主配置内存缓冲区的最大行数上限。