使用英语阅读

通过

了解和解决 Azure IoT 中心错误

  • 项目
  • 2025/05/09

本文介绍使用 IoT 中心时可能会遇到的常见错误代码的原因和解决方案。

400027连接在新连接上强制关闭

如果您的设备断开连接，并报告 Communication_Error 作为 ConnectionStatusChangeReason，且您使用的是 .NET SDK 和 MQTT 传输类型，那么可能会看到 400027 ConnectionForcefullyClosedOnNewConnection 错误。 或者，设备到云孪生操作（例如读取或修补已报告的属性）或直接方法调用失败，错误代码 400027。

当另一个客户端使用相同的标识创建与 IoT 中心的新连接时，会发生此错误，因此 IoT 中心将关闭以前的连接。 IoT 中心不允许多个客户端使用同一身份进行连接。

若要解决此错误，请确保每个客户端都使用自己的标识连接到 IoT 中心。

401003 IoT 中心未经授权

在日志中，你可能会看到一个模式：设备首先由于 401003 IoTHubUnauthorized 断开连接，紧接着是 404104 DeviceConnectionClosedRemotely，然后不久后又成功连接。

或者，对 IoT 中心的请求失败，并出现以下错误消息之一：

  • 缺少授权标头
  • IotHub“*”不包含指定的设备“*”
  • 授权规则“*”不允许访问“*”
  • 此设备的身份验证失败，续订令牌或证书并重新连接
  • 指纹与配置不匹配：指纹：SHA1Hash=*，SHA2Hash=*；配置：主指纹=*、副指纹=*
  • 由于没有分配的权限，主体 user@example.com 未获得 GET on /exampleOperation 的授权

发生此错误的原因是，对于 MQTT，某些 SDK 依赖于 IoT 中心在 SAS 令牌过期时发出断开连接，以了解何时刷新它。 因此：

  1. SAS 令牌过期
  2. IoT 中心注意到过期，并将设备与 401003 IoTHubUnauthorized 断开连接
  3. 设备通过使用 404104 DeviceConnectionClosedRemotely 完成断开连接。
  4. IoT SDK 生成新的 SAS 令牌
  5. 设备已成功重新连接到 IoT 中心

或者，IoT 中心无法对身份验证标头、规则或密钥进行身份验证。 这一结果可能是由于症状中提到的任何原因造成的。

若要解决此错误，如果使用 IoT SDK 通过设备连接字符串进行连接，则无需执行任何作。 IoT SDK 重新生成新令牌，以在 SAS 令牌过期时重新连接。

默认令牌生存期跨 SDK 为 60 分钟;但是，对于某些 SDK，令牌的有效期和令牌续订阈值是可配置的。 此外，当设备断开连接并重新连接令牌续订时生成的错误因每个 SDK 而异。 若要了解更多信息以及如何确定设备在日志中使用哪个 SDK，请参阅监控、诊断和排查 Azure IoT 中心设备连接的Azure IoT SDK 的 MQTT 设备断开连接行为部分。

对于设备开发人员来说，如果错误量是个问题，请切换到 C SDK，该 SDK 会在过期前续订 SAS 令牌。 对于 AMQP，SAS 令牌可以在不需要断开连接的情况下刷新。

通常，显示的错误消息应说明如何修复错误。 如果出于某种原因而无法访问错误消息详细信息，请确保：

  • 使用的 SAS 或其他安全令牌未过期。
  • 对于 X.509 证书身份验证，设备证书或与设备关联的 CA 证书不会过期。 若要了解如何向 IoT 中心注册 X.509 CA 证书，请参阅 教程：创建和上传用于测试的证书。
  • 对于 X.509 证书指纹身份验证，设备证书的指纹注册到 IoT 中心。
  • 授权凭据非常适合用于所使用的协议。 若要了解详细信息，请参阅 使用 Microsoft Entra ID 控制对 IoT 中心的访问。
  • 使用的授权规则拥有请求的操作权限。
  • 对于以“principal...”开头的最后一条错误消息，可以通过向用户分配正确的 Azure RBAC 权限级别来解决此错误。 例如，IoT 中心的所有者可以分配“IoT 中心数据所有者”角色，该角色提供所有权限。 请尝试此角色来解决缺少权限问题。

备注

当设备时间与服务器时间大于 5 分钟时，某些设备可能会遇到时间偏移问题。 设备可能在数周甚至数月内一直成功连接到 IoT 中心，但随后开始持续遭拒连接。 该错误也可以特定于连接到 IoT 中心的设备子集，因为时间偏移可能以不同的速率发生，具体取决于设备首次连接或打开的时间。

通常，使用 NTP 执行时间同步或重新启动设备（它可以在启动序列期间自动执行时间同步）可修复此问题，并允许设备再次连接。 若要避免此错误，请将设备配置为使用 NTP 执行定期时间同步。 可以计划每日、每周或每月的同步，具体取决于设备体验的偏移量。 如果无法在设备上配置定期 NTP 同步，请计划定期重启。

403002 IoT 中心配额已超出

你可能会看到对 IoT 中心的请求失败，错误代码 403002 IoTHubQuotaExceeded。 在 Azure 门户中，IoT 中心设备列表不会加载。

当超过 IoT 中心的每日消息配额时，通常会发生此错误。 解决此问题的方法是：

当注册到 IoT 中心的设备数接近或超过 IoT 中心的配额限制时，批量导入作业也可能返回此错误。 若要了解详细信息，请参阅“导入作业故障排除”部分，位于批量导入和导出 IoT 中心设备标识的页面中。

403004 设备的最大队列深度已超出

尝试发送云到设备的消息时，你可能会看到请求失败并出现错误 403004 或 DeviceMaximumQueueDepthExceeded。

此错误的根本原因是，设备的入队消息数超过 队列限制。

遇到此限制的最可能原因是使用 HTTPS 接收消息，这会导致使用 ReceiveAsync持续轮询，从而导致 IoT 中心限制请求。

使用 HTTPS 的云到设备消息支持的模式是间歇性连接的设备，这些设备不经常检查消息（不到每 25 分钟一次）。 为了降低达到队列限制的可能性，请切换到 AMQP 或 MQTT 用于云到设备消息通信。

或者，增强设备端逻辑以快速完成、拒绝或放弃排队消息、缩短生存时间或考虑发送更少的消息。 有关详细信息，请参阅《了解来自 IoT 中心的云到设备消息传送》的消息过期（生存时间）部分。

最后，请考虑使用清除队列 API，在达到限制之前定期清理未处理的消息。

403006超出设备最大活动文件上传限制

你可能会看到您的文件上传请求失败，错误代码为 403006 DeviceMaximumActiveFileUploadLimitExceeded，并带有消息“活动文件上传请求数不能超过10”。

发生此错误是因为每个设备客户端都受限于 并发文件上传。 如果设备在文件上传完成后未通知 IoT 中心，则可以轻松超过限制。 不可靠的设备端网络通常会导致此问题。

若要解决此错误，请确保设备可以及时 通知 IoT 中心文件上传完成。 然后，尝试 缩短文件上传配置的 SAS 令牌 TTL。

404001 找不到设备

在云到设备（C2D）通信（如 C2D 消息、孪生更新或直接方法）期间，你可能会发现操作失败，并显示404001 DeviceNotFound错误。

作失败，因为 IoT 中心找不到设备。 设备未注册或已禁用。

若要解决此错误，请注册所使用的设备 ID，然后重试。

404103设备未联机

你可能会发现，即使设备处于联机状态，指向设备的直接方法也会失败，报告错误404103 DeviceNotOnline。

如果您知道设备处于在线状态，但仍然收到错误信息，则可能是由于设备上未注册直接方法的回调函数导致的。

有关正确配置设备以便直接方法回调的详细信息，请参阅处理设备上的直接方法部分。

404104设备连接被远程关闭

你可能会看到设备定期断开连接（例如，每 65 分钟），并在 IoT 中心资源日志中看到 404104 DeviceConnectionClosedRemotely 。 有时还会看到 401003 IoTHubUnauthorized，然后不到一分钟后设备成功连接。

或者，设备随机断开连接，并在 IoT 中心资源日志中看到错误代码 404104 DeviceConnectionClosedRemotely。

或者，许多设备同时断开连接，您会在 连接的设备（connectedDeviceCount）指标中看到下降，并且在 Azure Monitor 日志中，404104 DeviceConnectionClosedRemotely 和 500xxx 内部错误 比平常多。

发生此错误的原因是 用于连接到 IoT 中心的 SAS 令牌 已过期，这会导致 IoT 中心断开设备的连接。 当设备刷新令牌时，将重新建立连接。 例如， 默认情况下，对于 C SDK，SAS 令牌每小时过期一次，这可能会导致定期断开连接。 若要了解详细信息，请参阅 401003 IoTHubUnauthorized。

其他一些可能性包括：

  • 设备失去网络连接的时间超过MQTT 保活时间，导致远程闲置超时。 MQTT 保持活动设置可以按设备不同。
  • 设备发送了 TCP/IP 级重置，但未发送应用程序级 MQTT DISCONNECT。 基本上，设备突然关闭了基础套接字连接。 有时，旧版 Azure IoT SDK 中的 bug 可能会导致此问题。
  • 设备端应用程序崩溃。

或者，IoT 中心可能会遇到暂时性问题。 有关详细信息，请参阅 500xxx 内部错误。

解决此问题的方法是：

我们建议使用 Azure IoT 设备 SDK 来可靠地管理连接。 若要了解详细信息，请参阅[管理设备重新连接以创建可复原的应用程序（iot-hub-reliability-features-in-sdks.md）

409001设备已存在

尝试在 IoT 中心注册设备时，你可能会看到请求失败，并出现错误 409001 DeviceAlreadyExists。

发生此错误的原因是 IoT 中心中已有具有相同设备 ID 的设备。

若要解决此错误，请使用其他设备 ID，然后重试。

您可能会在日志中看到错误 409002 LinkCreationConflict，同时伴随设备断开连接或云到设备消息失败。

通常，当 IoT 中心检测到客户端有多个连接时，会发生此错误。 事实上，当新的连接请求到达具有现有连接的设备时，IoT 中心会关闭现有连接，并出现此错误。

在最常见的情况下，单独的问题（如 404104 DeviceConnectionClosedRemotely）会导致设备断开连接。 设备尝试立即重新建立连接，但 IoT 中心仍认为设备已连接。 IoT 中心关闭以前的连接并记录此错误。

或者，有故障的设备端逻辑会导致设备在已有连接打开的情况下建立连接。

若要解决此错误，请在日志中查找可以排除的其他错误，因为此错误通常显示为其他暂时性问题的副作用。 否则，请确保仅在连接断开时发出新的连接请求。

412002设备消息锁丢失

尝试发送云到设备的消息时，你可能会看到请求失败并出现错误 412002 DeviceMessageLockLost。

发生此错误的原因是，当设备从队列（例如，使用 ReceiveAsync()）收到云到设备的消息时，IoT 中心会将消息锁定，锁定超时时间为1分钟。 如果设备在锁定超时过期后尝试完成消息处理，IoT 中枢将引发此异常。

如果 IoT Hub 在一分钟的锁定超时期间未收到通知，则会将消息恢复到排队状态。 设备可以尝试再次接收消息。 若要防止将来发生错误，请实现设备端逻辑，以便在收到消息后的一分钟内完成消息。 此一分钟的暂停无法更改。

429001限制异常

你可能会看到，对 IoT 中心的请求失败，并出现429001 ThrottlingException 错误。

当请求的操作超出 IoT 中心 调节限制 时，会发生此错误。

若要解决此错误，请检查您是否到达了速率限制，即通过将您的 遥测消息发送尝试 指标与之前指定的限制进行比较。 还可以检查 节流错误数量指标。 有关这些指标的信息，请参阅 设备遥测指标。 有关如何使用指标来帮助监视 IoT 中心的信息，请参阅 监视 Azure IoT 中心。

IoT 中心仅在违反限制过长一段时间后才返回 429 ThrottlingException。 设置此延迟是为了在 IoT 中心接收到突发流量时防止消息丢失。 在此期间，IoT 中心会按操作受限速率处理消息。如果积压了太多流量，则处理起来可能需要很长时间。 有关详细信息，请参阅 IoT 中心配额和限制的流量调整部分。

如果达到配额或节流限制，考虑纵向扩展 IoT 中心。

500xxx 内部错误

你可能会看到，对 IoT 中心的请求失败，并出现以 500 和/或某种“服务器错误”开头的错误。一些可能性包括：

  • 500001 ServerError：IoT 中心遇到了服务器端问题。

  • 500008 GenericTimeout：IoT 中心在超时之前无法完成连接请求。

  • ServiceUnavailable （无错误代码）：IoT 中心遇到内部错误。

  • InternalServerError （无错误代码）：IoT 中心遇到内部错误。

500xxx 错误响应的原因有很多。 在所有情况下，问题很可能是暂时性的。 虽然 IoT 中心团队努力维护 SLA，但 IoT 中心节点的小子集偶尔会遇到暂时性故障。 当设备尝试连接到出现问题的节点时，将收到此错误。

若要缓解 500xxx 错误，请在设备上执行重试操作。 若要 自动管理重试，请确保使用最新版本的 Azure IoT SDK。 有关暂时性故障处理和重试的最佳做法，请参阅 暂时性故障处理。

如果问题仍然存在，请检查 资源运行状况 和 Azure 状态 ，以查看 IoT 中心是否存在已知问题。 还可以使用 手动故障转移功能。

如果没有已知问题，问题仍然存在， 请联系支持人员 进行进一步调查。

找不到503003分区

你可能会看到对 IoT 中心的请求因 503003 PartitionNotFound 错误而失败。

此错误在 IoT 中心内部，可能是暂时性的。 有关详细信息，请参阅 500xxx 内部错误。

若要解决此错误，请参阅 500xxx 内部错误。

504101网关超时

尝试从 IoT 中心调用设备上的直接方法时，您可能会看到请求失败，并出现 504101 GatewayTimeout 错误。

发生此错误的原因是 IoT 中心遇到错误，无法确认直接方法是否在超时之前完成。或者，使用早期版本的 Azure IoT C# SDK （<1.19.0）时，设备与 IoT 中心之间的 AMQP 链接可能会因 bug 而以无提示方式删除。

若要解决此错误，请重试或升级到最新版本的 Azure IOT C# SDK。