故障排除

本页列出 MotioForge Studio 最常显示的错误和警告消息，并说明原因和解决步骤。完整的消息始终可以在端口控制台中查看。

端口和连接

消息	原因	解决方法
`[ERR] COM5: access denied`	COM 端口正被其他程序占用（Arduino IDE、串口监视器、另一个 MotioForge Studio 实例）。	关闭占用该端口的程序。如果问题仍然存在，请拔下并重新插入 USB 线。
`[ERR] COM port not found`	配置的 COM 编号与 Windows 检测到的任何设备都不匹配。	打开「设备管理器」→「端口 (COM 和 LPT)」查找正确的编号，并在端口编辑器中更新。
`[WRN] port already open`	MotioForge Studio 试图打开一个已经处于活动状态的端口。	非严重消息。如果端口响应正常，播放会继续。否则请在控制台中点击「断开」后重试。
`[ERR] handshake timeout`	所连接的 DEIMOS 控制板没有在预期时间内响应初始化消息。	检查固件是否为最新版本。拔下并重新插入 USB 线。检查控制板是否已通电。
`[ERR] invalid frame received`	数据损坏或协议错误。配置的波特率与硬件不一致。	在端口编辑器中检查波特率。DEIMOS 必须为 115200。对于 Arduino PWM，请检查已加载的 sketch。

舵机和元素

消息	原因	解决方法
`[WRN] Servo "X" — position Y° out of range`	某个片段试图让舵机超出元素编辑器中设置的最小/最大限制。	在片段编辑器中修改该片段，或在元素编辑器中扩大行程限制。
`[WRN] orphaned element: "X"`	某个片段引用了已在域中被删除或重命名的元素。	更新使用该缺失元素的片段，或用相同的名称重新创建该元素。
`[WRN] duplicate address: port Y, address Z`	两个域元素在同一端口上使用相同的地址（例如两个 ID=1 的舵机）。	在元素编辑器中检查物理地址。每个设备都必须有唯一的地址。
`[ERR] playback: port not open`	播放已开始，但所需的端口未能打开（之前出现过未显示的错误）。	查看控制台中之前的消息。检查硬件连接后重新开始播放。

音频

消息	原因	解决方法
`[ERR] audio file not found: "path"`	与 SOUND 片段关联的音频文件在保存的相对路径下不存在。	检查文件是否位于域的 `audio/` 文件夹中。重新打开该片段，并用「浏览」选择正确的文件。
`[ERR] unsupported audio format`	音频文件的格式无法被 MotioForge Studio 识别（例如 WMA、AIFF）。	使用任意免费转换工具（例如 Audacity、VLC）将文件转换为 WAV、MP3 或 OGG。
`[WRN] audio device unavailable`	MotioForge Studio 无法访问 Windows 音频设备（声卡被禁用或正被占用）。	在 Windows →「设置」→「声音」中检查是否已选择并启用了音频设备。

DEIMOS 固件

消息	原因	解决方法
`[ERR] firmware upload failed: arduino-cli not found`	arduino-cli 工具未安装，或不在系统 PATH 中。	MotioForge Studio 的资源中已包含 arduino-cli。如果错误仍然存在，请重新安装 MotioForge Studio 或联系技术支持。
`[ERR] firmware upload failed: port busy`	COM 端口仍被 MotioForge Studio 或其他软件占用。	加载固件前，请先在控制台中断开该端口。固件对话框会自动执行此操作；如果问题仍然存在，请关闭 MotioForge Studio，重新连接后再试。
`[ERR] integrity check failed`	固件程序包文件已损坏或未完整下载。	重新安装 MotioForge Studio，以恢复原始的固件程序包文件。
`[WRN] incompatible firmware version`	控制板上加载的固件与 MotioForge Studio 协议所需的版本不一致。	通过加载 DEIMOS 固件，使用当前版本 MotioForge Studio 附带的程序包更新固件。

域和文件

消息	原因	解决方法
`[ERR] cannot load domain`	`domain.json` 文件已损坏，或由不兼容版本的 MotioForge Studio 写入。	从备份中恢复该域。如果没有备份，请创建新域并手动重新配置。
`[WRN] animation has no segments`	所选动画不包含任何片段。播放会立即结束，没有任何动作。	开始播放前，请在主编辑器中至少添加一个片段。
`[ERR] domains folder not found`	在「设置 → 路径」中配置的文件夹不存在或无法访问。	打开设置 → 路径...并选择一个有效的文件夹。如果文件夹不存在，MotioForge Studio 会自动创建。

提示：在端口控制台中启用 Log I/O 选项，即可实时查看所有发送和接收的数据帧。这是诊断硬件通信问题最直接的方法。

另请参阅： 端口控制台 — 端口编辑器 — 加载 DEIMOS 固件 — AI 助手