OTA v5 报错与处理

App 0.6.0（含 OTA 诊断修复）· SecureLink 协议第 9 章 OTA wire v5 · 2026-09-27

升级页面上出现的每一种报错，都在下面的时序图里标出了发生位置，并在对应的表里写明它是什么意思、该去哪里查。联调时按编号对照即可。

怎么读 App 的报错

每个报错面板都由一行标题和三行说明组成

行内容
标题设备回报的错误以 Device reported <错误码> 开头；App 自己判定的错误直接写出问题，例如 Device did not answer QUERY_V5，不再借用设备错误码 INTERNAL。结果未知以 Upgrade result is not confirmed: 开头。
Expected:这一步 App 期待设备返回什么。
Observed:实际看到了什么，包括具体字段值和重连后读到的 DIS 版本。
Next:下一步该查什么。以 Firmware: 开头的交给固件侧处理。

「结果未知」为什么不能直接判成功或失败

协议第 9 章的成功判据要求五项同时满足：同一绑定的设备重新出现、fresh AUTH 成功、DIS 版本等于目标版本、QUERY_V5 返回这次 transfer 的 SUCCESS、没有回滚。少任何一项，App 都不能显示成功。APPLY 发出之后缺了其中一项，设备可能已经升级，也可能没有，这时只能显示结果未知。面板会写明缺的是哪一项。

A2失败D1结果未知A1弹窗C5自动处理，不报错

A 准备与预检

点 Start upgrade 到发出 OFFER_V5 之前，设备状态不会被改动

App设备出错点（编号见下表）点 Start upgrade：读绑定与 DIS 版本A1会话准备失败遗留 APPLY 记录仍在窗口内 → 转到阶段 E本地预检：包头 / 产品 / 目标版本A2设备已是该版本A3包比设备旧A4包属于别的产品A5包头被拒GET_CAPABILITIESA6GET_CAPABILITIES 无应答CAPABILITIESA7应答与请求对不上A8设备回 ERROR预检：能力 / 包大小A9能力不满足 wire v5A10包超出暂存容量
编号App 面板标题（原文）结果含义与处理
A1（弹窗「升级失败」，不进入升级）弹窗弹窗给出四种之一：请先重新连接并认证设备、该设备保存的身份已不匹配，请移除后重新配对、该设备不满足固件升级的前提条件。最后一种在联调中最常见：设备没暴露 Device Information Service（180A），或 DIS 固件版本不是 a.b.c.d 四段格式。
A2Device already runs 0.0.1.10失败包的目标版本与设备 DIS 版本相同，没有可装的内容。如果上一次升级显示结果未知，说明设备其实已经启动了这个版本。要再测一次 OTA，发布更高的版本，或打一个带 ALLOW_DOWNGRADE 标志的包。
A3Package 0.0.1.9 is older than the device's 0.0.1.10失败发布更高版本；确实要降级时打带 ALLOW_DOWNGRADE 的包。
A4Package is built for another product失败包头 productIdHash 与设备不一致。检查这台设备选择的发布通道和产品。
A5Package header was rejected失败重新构建并发布这个包。
A6Device did not answer GET_CAPABILITIES失败每次等 15 s，共发 3 次都没回。固件：在设备日志里确认收到了请求，并确认应答是从控制特征值发出的。
A7Device reply does not match the request失败Observed 行写明是哪个字段不符（这里是 transactionId）。App 已主动断开。固件：对照请求核对应答字段。
A8Device reported <错误码>: …失败设备明确拒绝，按错误码查（见文末错误码表）。
A9Device capabilities do not meet OTA wire v5失败Observed 行写明哪一项不满足，例如 device must advertise only OTA wire v5、device omits required OTA wire v5 features。固件：修正 CAPABILITIES 字段。
A10Package is larger than the device can stage失败Observed 行给出 包大小/maxModulePackage。缩小包，或在分区允许时提高固件的 maxModulePackage。

B 传输

OFFER_V5 到收齐全部数据；中断后都能从设备的 durable cursor 续传

App设备出错点（编号见下表）OFFER_V5（transferId、包身份、目标版本）B1OFFER_V5 无应答OFFER_ACCEPTED_V5（cursor）B2OFFER_REJECTED_V5B3应答与请求对不上B4cursor 越界FFB2 数据帧 × windowFramesTRANSFER_STATUS_V5 nonce=0（durable ACK）B5设备回终止类 ERRORB6ACK 不在帧边界等不到 ACK、写入结果不明或可续传类错误：自动 QUERY_V5 续传QUERY_V5B7QUERY_V5 无应答TRANSFER_STATUS_V5（durable cursor）B8cursor 不前进状态为 PAUSED：重发 matching OFFER_V5B9PAUSED 后不续传窗口循环，直到收齐
编号App 面板标题（原文）结果含义与处理
B1Device did not answer OFFER_V5失败每次等 15 s，共 3 次。固件：确认收到 OFFER_V5 并在控制特征值上应答。
B2Device reported <错误码>: OTA v5 offer rejected …失败设备在收包前拒绝，常见 VERSION_TOO_OLD、HARDWARE_MISMATCH、PAYLOAD_TOO_LARGE、KEY_ID_UNKNOWN。恢复动作是 RETRY_REQUEST 的（如 STAGING_UNAVAILABLE）App 会按 retryAfterMs 自动重发，最多 3 次。
B3Device reply does not match the request失败transferId、包大小或 requestNonce 不符，Observed 行写明是哪一条。App 已断开；再次开始会从设备的 durable cursor 续传。
B4Device returned an invalid cursor失败Expected / Observed 行给出 receivedOffset、dataPayloadBytes、windowFrames 的允许范围与实际值。固件：核对 OFFER_ACCEPTED_V5 / TRANSFER_STATUS_V5 的 cursor 字段。
B5Device reported <错误码>: …失败数据阶段收到恢复动作为 STOP、RESTART_TRANSFER、QUERY_ACTIVE 的错误（如 FLASH_WRITE_FAILED、TRANSFER_MISMATCH），按错误码查。
B6Device reply does not match the request失败Observed：window STATUS cursor is not a submitted frame boundary。设备确认的 offset 不是 App 发出的任何一帧的结尾。固件：检查 durable cursor 的推进逻辑。
B7Device did not answer QUERY_V5失败每次等 15 s，共 3 次。固件：确认传输中也能应答 QUERY_V5。
B8Device cursor stopped advancing失败同一 offset 恢复超过 3 次，或累计超过 10 次。Observed 行给出卡住的 offset。固件：查这个 offset 的帧为什么不被接受（CRC、写 flash、流控）。
B9Paused transfer was not resumed失败传输处于 PAUSED 时，App 重发 matching OFFER_V5，设备必须回 OFFER_ACCEPTED_V5 并带上 cursor。

C 校验与应用

设备验签，用户确认后 App 先持久保存 APPLY 意图，再发 APPLY_V5

App设备出错点（编号见下表）设备校验 hash 与签名TRANSFER_STATUS_V5 VERIFYING → READY_TO_APPLYC1校验超时C2校验失败C3ERROR 不带错误码C4意外状态用户确认 → 先持久保存 APPLY 意图APPLY_V5C5APPLY_V5 无应答C6APPLY 被拒TRANSFER_STATUS_V5 APPLYINGC7APPLY 后意外状态REBOOT_SCHEDULED_V5（rebootInMs、expectedReadyMs）C8REBOOT 字段无效C9REBOOT 前回 ERROR没收到 REBOOT_SCHEDULED_V5 不算错：直接进入重连
编号App 面板标题（原文）结果含义与处理
C1Device did not finish verifying the package失败设备迟迟不到 READY_TO_APPLY。固件：对比实际验签耗时与上报的 estimatedVerifyApplyMs，并确认校验结束时发出 TRANSFER_STATUS_V5。
C2Device reported <错误码>: OTA v5 terminal status …失败常见 HASH_MISMATCH、SIGNATURE_INVALID、TRUST_POLICY_CHANGED，按错误码查。
C3Device stopped the transfer without an error code失败状态为 ERROR 但 lastErrorCode 为 0。固件：进入 ERROR 时写入错误码。
C4Device reported <状态> while verifying失败Expected 行列出这一步允许的状态。固件：按 09 章核对这一步的状态机。
C5（不报错，转入阶段 D）自动处理无应答或写入结果不明时，APPLY 可能已经执行。App 不重发 APPLY，直接去重连和对账。
C6Device reported <错误码>: …失败如 APPLY_FAILED、BAD_STATE，按错误码查。
C7Device reported <状态> in reply to APPLY_V5失败期待 APPLYING、REBOOT_SCHEDULED 或 SUCCESS。
C8REBOOT_SCHEDULED_V5 has an invalid reboot delay失败另一条是 …invalid ready time。Expected 行给出允许范围：rebootInMs ≥ 500，expectedReadyMs ≥ rebootInMs（未知时填 0xffffffff）。transferId 或目标版本对不上则显示 Device reply does not match the request。
C9Device reported <错误码>: …失败按错误码查。

D 重启与重连

APPLY 发出之后的报错都是结果未知：设备可能已经升级

App设备出错点（编号见下表）设备重启，进入新固件扫描已绑定设备并建链D1设备没回来fresh OwnerKey AUTHD2连上但 AUTH 未完成D3没有 fresh AUTHD4连到了别的绑定读 DIS 固件版本D5身份或 DIS 校验失败
编号App 面板标题（原文）结果含义与处理
D1Upgrade result is not confirmed: Device did not come back after reboot结果未知截止前一次都没连上。Observed 行带最后一次失败原因。固件：确认设备真的重启了、启动耗时没超过上报的 expectedReadyMs、重启后以 BOUND 标志和相同 discriminator 广播。
D2Upgrade result is not confirmed: Device came back but Owner AUTH did not complete结果未知固件：查新固件启动后的 AUTH 日志；新镜像可能丢了绑定或 OwnerKey。
D3Upgrade result is not confirmed: Reconnected without a fresh Owner AUTH结果未知查 App 和设备两边这次重连的 AUTH 日志。
D4Upgrade result is not confirmed: Reconnected to a different binding结果未知两台已绑定设备的 discriminator 可能相同；升级时只留目标设备在附近。
D5Upgrade result is not confirmed: Could not reconnect to the device after APPLY结果未知Observed 行是具体原因，例如 DIS 固件版本缺失或不是四段格式、保存的身份在升级中被改动。

重连截止时间：收到 REBOOT_SCHEDULED_V5 时，从收到起算 expectedReadyMs + max(10 s, expectedReadyMs/2) + 2 s，设备报 ETA 未知时按 60 s 计；没收到时是 APPLY 截止时间再加 120 s。手机中途重启的话，再给一次 120 s 的只读对账窗口。

E 对账

重连并 fresh AUTH 后用 QUERY_V5 读取这次 transfer 的最终状态

App设备出错点（编号见下表）QUERY_V5（transferId）E1QUERY_V5 无应答E2回终止类 ERRORE3回可恢复 ERRORE4应答与请求对不上TRANSFER_STATUS_V5 SUCCESSE5SUCCESS 但带错误字段E6SUCCESS 但 DIS 不是目标版本SUCCESS + DIS = 目标版本 + 无错误字段 → Upgrade succeededTRANSFER_STATUS_V5 其他状态E7状态为 ERRORE8APPLY 后变 CANCELLEDE9窗口结束仍在 APPLYINGE10已是目标版本仍 READY_TO_APPLYE11其他状态窗口内仍 APPLYING / REBOOT_SCHEDULED：等待后重连再查READY_TO_APPLY 且 APPLY 从未开始：自动重发或请用户再次确认
编号App 面板标题（原文）结果含义与处理
E1Upgrade result is not confirmed: Device did not answer QUERY_V5结果未知Observed 行附带重连后读到的 DIS 版本。固件：新固件启动后必须应答这次 transfer 的 QUERY_V5。
E2Device reported TRANSFER_NOT_FOUND: …（附诊断）失败恢复动作为 STOP / RESTART_TRANSFER / QUERY_ACTIVE 的错误以失败结束，但面板带诊断，本地仍记为结果未知。最常见的是 TRANSFER_NOT_FOUND：固件需要跨重启保留这次 transfer 的结果，让 QUERY_V5 能返回 SUCCESS（09 章成功判据）。
E3Upgrade result is not confirmed: Device answered QUERY_V5 with <错误码>结果未知恢复动作为 QUERY_AND_RESUME / REAUTHENTICATE 的错误。按错误码查设备日志。
E4Upgrade result is not confirmed: Device reply does not match the request结果未知Observed 行写明哪个字段不符，并附 DIS 版本。
E5Upgrade result is not confirmed: Device reported SUCCESS with error fields set结果未知固件：以 SUCCESS 结束时清零 lastError 与 recoveryAction，否则改报 ERROR。
E6Upgrade result is not confirmed: Device reported SUCCESS but does not run 0.0.1.10结果未知固件：确认新镜像启动且没有回滚，DIS 报的是正在运行的镜像版本。
E7Device reported <错误码>: …失败按错误码查。若 ERROR 不带错误码，显示为结果未知：Device stopped the transfer without an error code。
E8Upgrade result is not confirmed: Transfer shows CANCELLED after APPLY had started结果未知固件：已执行 APPLY 的 transfer 不能回到 CANCELLED；查 APPLY 前后的设备日志。
E9Upgrade result is not confirmed: Device was still applying when the recovery window ended结果未知固件：对比实际应用和启动耗时与上报的 estimatedVerifyApplyMs、expectedReadyMs。重新打开页面即可再查一次。
E10Upgrade result is not confirmed: Device runs 0.0.1.10 but the transfer is still READY_TO_APPLY结果未知固件：启动新镜像后，把这次 transfer 记为 SUCCESS，让 QUERY_V5 能报告。
E11Upgrade result is not confirmed: Transfer state does not match an upgrade that was applied结果未知期待 SUCCESS、ERROR、APPLYING 或 REBOOT_SCHEDULED。按 transferId 查设备日志。

重新打开升级页面时

App 先用 DIS 版本处理上次留下的 APPLY 记录

设备错误码

面板标题里 Device reported 后面的名称；恢复动作由协议规定

CodeerrorCoderecoveryActionApp 处理
0x01BAD_OPCODESTOP失败
0x02BAD_STATEQUERY_ACTIVE失败
0x04NOT_AUTHORIZEDREAUTHENTICATE传输中：自动 QUERY_V5 续传；对账时：结果未知
0x05BUSYQUERY_ACTIVE失败
0x06CONTROL_FRAME_MALFORMEDSTOP失败
0x10VERSION_TOO_OLDSTOP失败
0x11HARDWARE_MISMATCHSTOP失败
0x12PAYLOAD_TOO_LARGESTOP失败
0x13PRODUCT_MISMATCHSTOP失败
0x17PACKAGE_FORMAT_INVALIDSTOP失败
0x18STAGING_UNAVAILABLERETRY_REQUESTOFFER 阶段：按 retryAfterMs 重发，最多 3 次
0x19SIGNATURE_SCHEME_UNSUPPORTEDSTOP失败
0x1AKEY_ID_UNKNOWNSTOP失败
0x1BDATA_FRAME_SIZE_UNSUPPORTEDSTOP失败
0x1CPRIVILEGED_FLAG_NOT_AUTHORIZEDSTOP失败
0x1DTRUST_POLICY_CHANGEDSTOP失败
0x1ESECURITY_VERSION_ROLLBACKSTOP失败
0x20TRANSFER_TIMEOUTQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x21CRC_FAILQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x22TRANSFER_MISMATCHRESTART_TRANSFER失败
0x23DATA_FRAME_MALFORMEDQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x24DATA_LENGTH_INVALIDQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x25SEQ_DUPLICATEQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x26SEQ_GAPQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x27FLASH_WRITE_FAILEDSTOP失败
0x28TRANSFER_NOT_FOUNDRESTART_TRANSFER失败
0x29FLOW_CONTROL_VIOLATIONQUERY_AND_RESUME传输中：自动 QUERY_V5 续传；对账时：结果未知
0x30HASH_MISMATCHSTOP失败
0x31SIGNATURE_INVALIDSTOP失败
0x40APPLY_FAILEDSTOP失败
0x41ROLLBACKSTOP失败
0xF0INTERNALSTOP失败
recoveryAction协议含义
QUERY_AND_RESUME停发数据帧，QUERY_V5 取 durable cursor，再以 matching OFFER_V5 续传
RETRY_REQUEST等待 retryAfterMs 后重发同一条请求
RESTART_TRANSFER放弃当前 transferId，以新 transferId 重新 OFFER_V5
REAUTHENTICATE断开并重新完成 fresh OwnerKey AUTH
QUERY_ACTIVEQUERY_V5 读取设备当前活动 transfer 后再决定
STOP终止本次升级，不得重试