出问题时，EmbodiFlow 会尽量准确地告诉你问题在哪。main.py 里的问题会标出行号和列号；工作流里的问题会指出步骤和字段。每个错误还有一个错误码，本页逐一解释。下面的文字由控制台、CLI 和 MCP 工具共用的同一份文案生成，所以和你看到的始终一致。
看懂一次运行
步骤以 succeeded、failed、not applicable 或 skipped 之一结束。只有 succeeded 是绿色；不适用和已跳过的步骤是灰色。失败的步骤显示 <code>: <message>，回溯在日志里。
被跳过的步骤总会说明原因：条件不成立、上游步骤失败、停止型质检停止了录制、步骤没有任务片段，或者这是一次时间窗口测试运行，它不保存结果。
质检结果也是同样的道理。结果是 pass、warn、fail、error、not_evaluated 或 not_applicable 之一，只有 pass 是绿色。
错误码
ALGORITHM_CATEGORY_INVALID: 算法类别不存在
原因： 装饰器或 algorithm.yaml 写了一个不存在的类别。
处理： 改用 standardize、check、transform、enrich、segment、curate 或 export。
ALGORITHM_INTERFACE_CHANGED: 接口已变化，需保存为主版本
原因： 端口、级别、requires、声明的特征、质检项、标签或参数类型发生了变化，沿用当前主版本的工作流会出错。
处理： 保存建议的主版本。工作流在切换前继续使用旧的主版本。
ALGORITHM_MANIFEST_DRIFT: 代码与已保存的接口不一致
原因： main.py 中装饰器描述的接口与保存该版本时冻结的接口不同，步骤未启动。
处理： 重新保存算法，从当前代码重新提取接口。
FEATURE_ROW_COUNT_MISMATCH: 逐帧数值没有覆盖每一帧
原因： 某个逐帧特征的行数与录制的帧数不同。
处理： 每帧写一行。没有数值的帧写 NaN 或 -1。
FEATURE_TYPE_UNKNOWN: 特征类型不存在
原因： 某个特征、标签或输入要求写了注册表中没有的语义类型。
处理： 改用注册表中的类型，例如 scalar、vector、pose.se3 或 json。
EPISODES_INVALID: 片段无效
原因： 某个片段为空、超出录制范围、与其他片段重叠，或带有未声明的标签。
处理： 写出录制范围内互不重叠的时间段，并声明每个标签键。
EPISODES_INPUT_MISSING: 上一步没有给出片段列表
原因： 负责划分片段的步骤结束时没有保存片段列表，当前步骤无从运行。
处理： 不复用之前的结果，重新运行整个工作流；或检查划分片段的步骤是否成功。
SELECTION_INVALID: 整理决定无效
原因： 某个决定指向源版本之外的片段、对同一片段决定了两次、丢弃片段时没有原因，或汇总数字不对。
处理： 对源版本的每个片段最多决定一次，并为每个丢弃的片段写明原因。
CURATE_SELECTION_CONFLICT: 两个整理步骤做了同一决定
原因： 有多个整理步骤设置了划分，或有多个设置了任务文本，新版本会取决于它们的先后顺序。
处理： 让一个整理步骤负责划分，一个负责任务文本。
WORKFLOW_CONTENT_MISSING: 连接缺少输入所需的内容
原因： 该输入需要的特征类型，所连接的输出没有声明。
处理： 连接声明了所需类型的输出，或添加能生成它的步骤。
WORKFLOW_NO_STANDARDIZE: 工作流没有标准化步骤
原因： 处理工作流保存的录制必须来自唯一一个标准化步骤。
处理： 添加标准化步骤（或 uses: auto），并把它的录制连向输出节点。
WORKFLOW_EPISODES_MISMATCH: 逐片段数值会挂到别的片段上
原因： 片段级步骤读取的片段与输出节点保存的片段来自不同的步骤。
处理： 把该步骤和输出节点连到同一个片段输出。
WORKFLOW_PRIVACY_BARRIER: 会在匿名化之前读取画面
原因： 某个步骤或输出节点读取录制的路径没有经过匿名化步骤，需要隐私保护的录制只能在匿名化之后读取。
处理： 改为把该步骤连到匿名化步骤的输出。
WORKFLOW_STOPPED_BY_CHECK: 被质检项停止
原因： 一个设置为失败即停止的质检项未通过，其余步骤没有运行，这段录制没有保存任何结果。
处理： 打开质检结果查看失败原因。修正数据或把该质检项改为继续，然后重新运行工作流。
OUTPUT_ERROR: 算法写出了无效的输出
原因： 某个输出不符合约定：名称未声明、形状或类型不对，或缺少文件。
处理： 在步骤消息中查看出错的字段，修正代码后在样本上测试。
EXPORT_ARTIFACT_EMPTY: 导出没有写出文件
原因： 导出步骤至少要写出一个文件，平台会把文件打包成 export.zip，供下载和训练使用。
处理： 用 ArtifactWriter（out.path 或 out.add）写出至少一个文件；镜像写到 /embodiflow/output/<port>/ 下。先在样本上测试。
EXPORT_PACKAGE_MISSING: 平台没有打包导出文件
原因： 导出步骤写出了文件，但平台没有收到 export.zip。平台在步骤结束时打包，可能是平台步骤镜像过旧或打包失败。
处理： 重新运行导出。如果仍然失败，请平台运维更新 flow-io 镜像。
WORKFLOW_COMMIT_FAILED: 平台没能保存步骤输出
原因： 步骤已完成并写出输出，但平台在记录输出时出错。问题在平台，不在步骤或输入。
处理： 重新运行工作流。如果仍然失败，请把运行 ID 发给平台运维。
OUTPUT_FILE_NOT_REGULAR: 输出是链接而不是文件
原因： 步骤在输出中留下了符号链接或其他非普通文件。平台不会跟随链接，因此没有保存任何输出。
处理： 把文件复制到输出目录，不要创建链接，然后重新运行步骤。
CURATE_NOTHING_KEPT: 所有片段都被丢弃
原因： 整理决定丢弃了源版本的全部片段，新版本没有内容。步骤消息列出每种丢弃原因及数量；quality: not_evaluated 表示部分已启用的检查没有运行。
处理： 放宽整理设置，至少保留一个片段，或补齐缺少的检查，然后重新运行工作流。
CURATE_SOURCE_VERSION_UNUSABLE: 源版本无法整理
原因： 源数据集版本已被脱敏删除，或没有数据契约摘要。
处理： 改在未脱敏删除的版本上运行整理工作流，或先创建新版本。
CURATE_TASK_CHANGE_UNSUPPORTED: 整理暂不能修改任务文本
原因： 整理步骤为保留的片段设置了任务文本，而版本会冻结每个片段的任务。
处理： 去掉整理步骤里的任务决定，或修改片段任务后创建新版本。
CURATE_RUN_UNREADABLE: 无法读取整理运行
原因： 运行没有可读的工作流快照或源版本，或团队没有可用的存储。
处理： 从版本页面重新运行整理工作流；如仍出现请联系支持。
ALGORITHM_FILE_INVALID: 算法不符合规则
原因： main.py 中的接口（或镜像的 algorithm.yaml）违反了某条规则，消息中写明了行号或字段。
处理： 修正消息指出的那一行。装饰器参数和参数默认值必须是直接写出的值，不能是计算得到的。
ALGORITHM_GPU_UNSATISFIABLE: 没有合适的 GPU
原因： 算法要求的显存超过了本平台任何计算池能提供的显存。
处理： 在 resources 中降低显存要求，或请管理员配置更大的 GPU 型号。
ALGORITHM_PARAM_INVALID: 参数值不合适
原因： 某个值不是已声明的参数、类型不对，或超出了范围。
处理： 使用参数声明的名称、类型和范围，或省略该值以使用默认值。
ALGORITHM_SAMPLE_RUN_INPUT_INVALID: 样本与算法不匹配
原因： 所选输入不是算法要读取的类型：录制、片段或数据集版本，或者窗口不被允许。
处理： 录制级算法选择录制，片段级算法选择片段，整理和导出选择数据集版本。
RECORDING_SCHEMA_NOT_READY: 录制还没有处理结果
原因： 这段录制尚未处理完成，相机、列和特征还不可知。
处理： 等待处理完成，或选择另一段录制。
SAMPLE_PREVIEW_INVALID: 样本已运行，但没有预览
原因： 运行生成的预览过大或无效，已被丢弃，运行结果不变。
处理： 缩短窗口后重新运行样本。仍然如此请反馈。