Azure IoT Hub 오류 이해 및 해결

  • 아티클

이 문서에서는 IoT Hub를 사용하는 동안 발생할 수 있는 일반적인 오류 코드의 원인과 해결 방법에 대해 설명합니다.

400027 연결이 새 연결에서 강제로 닫힘

디바이스 연결이 끊기고 .NET SDK 및 MQTT 전송 유형을 사용하여 ConnectionStatusChangeReason으로 Communication_Error가 보고되는 경우 400027 ConnectionForcefullyClosedOnNewConnection 오류가 표시될 수 있습니다. 또는 디바이스-클라우드 쌍 작업(예: 보고된 속성 읽기 또는 패치) 또는 직접 메서드 호출이 실패하고 오류 코드 400027이 표시됩니다.

이 오류는 다른 클라이언트가 동일한 ID를 사용하여 IoT Hub에 새 연결을 만들 때 발생하므로 IoT Hub는 이전 연결을 종료합니다. IoT Hub는 같은 ID에 여러 클라이언트가 연결하는 것을 허용하지 않습니다.

이 오류를 해결하려면 각 클라이언트가 고유의 ID를 사용하여 IoT Hub에 연결되도록 합니다.

401003 IoT Hub 권한 없음

로그를 보면 401003 IoTHubUnauthorized, 404104 DeviceConnectionClosedRemotely가 차례로 표시되면서 디바이스 연결이 끊기고, 잠시 후 성공적으로 연결되는 디바이스 패턴이 목격될 수 있습니다.

또는 IoT Hub 요청이 실패하고 다음 오류 메시지 중 하나가 표시됩니다.

  • 권한 부여 헤더 누락
  • IotHub ‘*’에 지정된 ‘*’ 디바이스가 없음
  • 권한 부여 규칙 ‘*’에서 ‘*’에 대한 액세스를 허용하지 않음
  • 이 디바이스에 대한 권한 부여 실패, 토큰 또는 인증서 갱신 및 다시 연결
  • 지문이 구성과 일치하지 않음. 지문: SHA1Hash=*, SHA2Hash=*, 구성: PrimaryThumbprint=*, SecondaryThumbprint=*
  • 보안 주체 user@example.com은 할당된 권한이 없기 때문에 /exampleOperation에서 GET에 대한 권한이 없음

MQTT의 경우 일부 SDK는 새로 고칠 시기를 파악하기 위해 IoT Hub를 사용하여 SAS 토큰이 만료될 때 연결을 해제하므로 이 오류가 발생합니다. 따라서

  1. SAS 토큰이 만료됩니다.
  2. IoT Hub가 만료를 알리고 디바이스 연결을 해제하고 401003 IoTHubUnauthorized를 표시합니다.
  3. 디바이스가 연결 해제를 완료하고 404104 DeviceConnectionClosedRemotely를 표시합니다.
  4. IoT SDK가 새 SAS 토큰을 생성합니다.
  5. 디바이스가 IoT Hub와 성공적으로 다시 연결됩니다.

또는 IoT Hub가 권한 부여 헤더, 규칙 또는 키를 인증할 수 없습니다. 증상에 언급된 이유 중 어느 것이라도 원인일 수 있습니다.

디바이스 연결 문자열을 사용하는 연결에 IoT SDK를 사용하는 경우 이 오류를 해결하기 위해 작업을 수행할 필요가 없습니다. IoT SDK는 새 토큰을 다시 생성하여 SAS 토큰 만료 시 다시 연결합니다.

기본 토큰 수명은 SDK 전체에서 60분입니다. 그러나 일부 SDK의 경우 토큰 수명 및 토큰 갱신 임계값을 구성할 수 있습니다. 또한 디바이스가 연결 해제되고 토큰 갱신 시 다시 연결하는 경우 생성되는 오류는 SDK마다 다릅니다. 자세한 내용과 디바이스에서 로그에 사용 중인 SDK를 확인하는 방법은 Azure IoT SDK를 사용하여 MQTT 디바이스 연결 해제 동작을 참조하세요.

디바이스 개발자의 경우 오류 볼륨이 문제가 되면 C SDK로 전환합니다. 그러면 만료되기 전에 SAS 토큰을 갱신합니다. AMQP의 경우 SAS 토큰은 연결을 해제하지 않고 새로 고칠 수 있습니다.

일반적으로 오류를 해결하는 방법을 설명하는 오류 메시지가 표시됩니다. 어떤 이유로든 오류 메시지 세부 정보에 액세스할 수 없는 경우 다음을 확인합니다.

  • SAS 또는 사용하는 기타 보안 토큰이 만료되지 않았는지 확인합니다.
  • X.509 인증서 인증의 경우 디바이스와 연결된 디바이스 인증서 또는 CA 인증서가 만료되지 않았는지 확인합니다. IoT Hub에 X.509 CA 인증서를 등록하는 방법은 자습서: 테스트를 위한 인증서 만들기 및 업로드를 참조하세요.
  • X.509 인증서 지문 인증의 경우 디바이스 인증서의 지문이 IoT Hub에 등록되었는지 확인합니다.
  • 권한 부여 자격 증명이 사용하는 프로토콜에 맞게 구성되었는지 확인합니다. 자세히 알아보려면 IoT Hub에 대한 액세스 제어를 참조하세요.
  • 사용된 권한 부여 규칙에 요청된 작업에 대한 권한이 있는지 확인합니다.
  • "principal..."로 시작하는 마지막 오류 메시지의 경우 사용자에게 올바른 수준의 Azure RBAC 권한을 할당하여 이 오류를 해결할 수 있는지 확인합니다. 예를 들어 IoT Hub 소유자는 모든 권한을 부여하는 "IoT Hub 데이터 소유자" 역할을 할당할 수 있습니다. 권한 부족 문제를 해결하려면 이 역할을 시도하세요.

참고 항목

일부 디바이스는 디바이스 시간이 서버와 5분 이상 차이가 있는 경우 시간 드리프트 문제가 발생할 수 있습니다. 이 오류는 디바이스가 몇 주 또는 몇 달 동안 문제 없이 IoT Hub에 연결되었지만 계속해서 연결이 거부되기 시작하는 경우에 발생할 수 있습니다. 디바이스가 처음 연결되거나 켜져 있는 시기에 따라 시간 드리프트가 다른 속도로 발생할 수 있기 때문에 이 오류는 IoT Hub에 연결된 디바이스의 하위 집합과 관련이 있을 수도 있습니다.

종종 NTP를 사용하여 시간 동기화를 수행하거나 디바이스를 다시 부팅하면(부팅 시퀀스 중에 시간 동기화를 자동으로 수행할 수 있음) 문제가 해결되고 디바이스를 다시 연결할 수 있습니다. 이 오류를 방지하려면 NTP를 사용하여 주기적인 시간 동기화를 수행하도록 디바이스를 구성합니다. 디바이스 환경의 드리프트 양에 따라 매일, 매주 또는 매월 동기화를 예약할 수 있습니다. 디바이스에서 정기적인 NTP 동기화를 구성할 수 없는 경우에는 정기적인 다시 부팅을 예약합니다.

403002 IoT Hub 할당량이 초과됨

IoT Hub에 대한 요청이 실패하고 403002 IoTHubQuotaExceeded 오류가 표시될 수 있습니다. 그리고 Azure Portal에서 IoT 허브 디바이스 목록이 로드되지 않습니다.

이 오류는 일반적으로 IoT Hub의 일일 메시지 할당량을 초과할 때 발생합니다. 이 오류를 해결하려면 다음을 수행합니다.

이 오류는 IoT 허브에 등록된 디바이스 수가 IoT 허브의 할당량 한도에 근접하거나 초과하는 경우 대량으로 가져오기 작업에서 반환될 수도 있습니다. 자세한 내용은 가져오기 작업 문제 해결을 참조하세요.

403004 디바이스 최대 큐 크기를 초과했음

클라우드-디바이스 메시지를 보내려고 하면 요청이 실패하고 403004 또는 DeviceMaximumQueueDepthExceeded 오류가 표시될 수 있습니다.

이 오류의 근본 원인은 디바이스의 큐에 넣은 메시지 수가 큐 제한을 초과하기 때문입니다.

이 제한에 도달하는 가장 큰 이유는 HTTPS를 사용하여 메시지를 수신하고 있기 때문입니다. 이로 인해 ReceiveAsync를 사용하는 지속적인 폴링이 발생하여 IoT Hub가 요청을 제한합니다.

HTTPS에서 클라우드-디바이스 메시지에 대해 지원되는 패턴은 메시지를 가끔씩(25분에 한 번씩보다 적게) 확인하는 디바이스에 간헐적으로 연결됩니다. 큐 제한에 도달 가능성을 줄이려면 클라우드-디바이스 메시지에 대해 AMQP 또는 MQTT로 전환합니다.

또는 큐에 넣은 메시지를 빠르게 완료, 거부 또는 폐기하도록 디바이스 측 논리를 강화하거나 TTL(Time to Live)을 단축시키고 보내는 메시지 수를 줄이는 것이 좋습니다. C2D 메시지 TTL(Time to Live)을 참조하세요.

마지막으로, 제한에 도달하기 전에 큐 API 제거를 사용하여 보류 중인 메시지를 정기적으로 정리하는 것이 좋습니다.

403006 디바이스 최대 활성 파일 업로드 제한을 초과했습니다.

오류 코드 403006 DeviceMaximumActiveFileUploadLimitExceeded과 함께 파일 업로드 요청이 실패하고 “Number of active file upload requests cannot exceed 10(활성 파일 업로드 요청 수는 10개를 초과할 수 없습니다.)”라는 메시지가 표시될 수 있습니다.

이 오류는 각 디바이스 클라이언트의 동시 파일 업로드가 제한되어 있기 때문에 발생합니다. 파일 업로드가 완료되었을 때 디바이스가 IoT Hub에 알리지 않으면 제한을 쉽게 초과할 수 있습니다. 이 문제는 일반적으로 신뢰할 수 없는 디바이스 측 네트워크로 인해 발생합니다.

이 오류를 해결하려면 디바이스가 IoT Hub 파일 업로드 완료 사실을 즉시 알릴 수 있게 해야 합니다. 그런 다음 파일 업로드 구성을 위해 SAS 토큰 TTL을 줄여보세요.

404001 디바이스를 찾을 수 없음

C2D 메시지, 트윈 업데이트 또는 직접 메서드와 같은 C2D(클라우드-디바이스) 통신 중에 404001 DeviceNotFound 오류와 함께 작업이 실패할 수 있습니다.

IoT Hub에서 디바이스를 찾을 수 없어 작업이 실패했습니다. 디바이스가 등록되지 않았거나 사용하도록 설정되지 않았습니다.

이 오류를 해결하려면 사용한 디바이스 ID를 등록하고 다시 시도해 보세요.

404103 디바이스가 온라인 상태가 아님

디바이스가 온라인 상태인 경우에도 디바이스에 대한 직접 메서드가 실패하고 404103 DeviceNotOnline 오류가 표시될 수 있습니다.

디바이스가 온라인 상태이지만 여전히 오류가 발생하는 경우 디바이스에 직접 메서드 콜백이 등록되어 있지 않기 때문에 오류가 발생했을 가능성이 높습니다.

직접 메서드 콜백에 대한 디바이스를 올바르게 구성하려면 디바이스에서 직접 메서드 처리를 참조하세요.

404104 디바이스 연결이 원격으로 닫힘

디바이스의 연결이 정기적으로 끊어지고(예: 65분마다) IoT Hub 리소스 로그에 404104 DeviceConnectionClosedRemotely가 표시될 수 있습니다. 경우에 따라 401003 IoTHubUnauthorized가 표시되고 1분도 지나지 않아 디바이스의 성공적인 연결 이벤트도 확인할 수 있습니다.

또는 디바이스의 연결이 임의로 끊어지고 IoT Hub 리소스 로그에 404104 DeviceConnectionClosedRemotely가 표시됩니다.

또는 여러 디바이스에서 한 번에 연결이 끊기면 연결된 디바이스(connectedDeviceCount) 메트릭에 DIP가 표시되고, Azure Monitor 로그에는 평소보다 많은 404104 DeviceConnectionClosedRemotely 및 500xxx 내부 오류가 나타납니다.

IoT Hub 연결에 사용되는 SAS 토큰이 만료되어 IoT Hub에서 디바이스 연결이 끊어지므로 이 오류가 발생할 수 있습니다. 디바이스에서 토큰을 새로 고칠 때 연결이 다시 설정됩니다. 예를 들어 기본적으로 C SDK에 대해 SAS 토큰이 매시간 만료되므로 정기적으로 연결이 끊어질 수 있습니다. 자세히 알아보려면 401003 IoTHubUnauthorized를 참조하세요.

그 외에도 다음과 같은 원인으로 오류가 발생할 수 있습니다.

  • 디바이스에서 MQTT keep-alive보다 오래된 기본 네트워크 연결이 끊어져 원격 유휴 시간 제한이 발생했습니다. MQTT keep-alive 설정은 디바이스별로 다를 수 있습니다.
  • 디바이스가 TCP/IP 수준 다시 설정을 전송했지만 애플리케이션 수준 MQTT DISCONNECT를 전송하지 않았습니다. 기본적으로 디바이스는 기본 소켓 연결을 갑자기 닫았습니다. 경우에 따라 이 문제는 이전 버전의 Azure IoT SDK의 버그로 인해 발생합니다.
  • 디바이스 측 애플리케이션 크래시가 발생했습니다.

또는 IoT Hub에서 일시적인 문제가 발생할 수 있습니다. IoT Hub 내부 서버 오류를 참조하세요.

이 오류를 해결하려면 다음을 수행합니다.

  • 오류 401003 IoTHubUnauthorized에 대한 지침을 참조하세요.
  • 연결 테스트를 통해 디바이스가 IoT Hub에 제대로 연결되었는지 확인합니다. 네트워크가 불안정하거나 일시적인 연결인 경우 탐지(예: Azure Monitor 경고를 통함) 시간이 더 오래 걸릴 수 있기 때문에 keep-alive 값을 늘리지 않는 것이 좋습니다.
  • 최신 버전의 IoT SDK를 사용합니다.
  • IoT Hub 내부 서버 오류에 대한 지침을 참조하세요.

Azure IoT 디바이스 SDK를 사용하여 연결을 신뢰할 수 있도록 관리하는 것이 좋습니다. 자세한 내용은 Azure IoT Hub 디바이스 SDK를 사용하여 연결 및 신뢰할 수 있는 메시지 관리에서 확인할 수 있습니다.

409001 디바이스가 이미 있음

디바이스를 IoT Hub에 등록하려고 하면 409001 DeviceAlreadyExists 오류와 함께 요청이 실패할 수 있습니다.

IoT 허브에 디바이스 ID가 같은 디바이스가 이미 있기 때문에 이 오류가 발생합니다.

이 오류를 해결하려면 다른 디바이스 ID를 사용하고 다시 시도해 보세요.

디바이스 연결 끊김 또는 클라우드 - 디바이스 메시지 오류와 함께 409002 LinkCreationConflict가 로그에 표시될 수 있습니다.

일반적으로 이 오류는 IoT Hub가 클라이언트에 둘 이상의 연결이 있는 것을 탐지했을 때 발생합니다. 실제로 기존 연결 중인 디바이스에 새 연결 요청이 오면 IoT Hub는 이 오류로 기존 연결을 닫습니다.

가장 일반적인 경우 별도의 문제(예: 404104 DeviceConnectionClosedRemotely)로 인해 디바이스 연결이 끊어집니다. 디바이스는 즉시 연결을 다시 설정하려고 하지만 IoT Hub는 여전히 이 디바이스가 연결된 것으로 인식합니다. IoT Hub는 이전 연결을 닫고 이 오류를 기록합니다.

또는 잘못된 디바이스 측 논리로 인해 디바이스가 이미 열려 있을 때 디바이스에서 연결을 설정합니다.

이 오류는 일반적으로 다른 일시적인 문제의 부작용으로 나타나므로 이 오류를 해결하려면 문제를 해결할 수 있는 다른 오류를 로그에서 찾아 보세요. 그렇지 않으면, 연결이 끊어질 경우만 새 연결 요청을 발급해야 합니다.

412002 디바이스 메시지 잠금 손실

클라우드-디바이스 메시지를 전송하려고 하면 요청이 실패하고 412002 DeviceMessageLockLost 오류가 표시될 수 있습니다.

디바이스가 큐에서 클라우드-디바이스 메시지를 수신하면(예: ReceiveAsync() 사용) 잠금 시간 제한 1분 동안 IoT Hub가 메시지를 잠그기 때문에 이 오류가 발생합니다. 잠금 시간 제한이 만료된 후 디바이스가 메시지를 완료하려고 하면 IoT Hub가 이 예외를 throw합니다.

IoT Hub가 1분 잠금 시간 제한 내에 알림을 받지 못하면 메시지를 다시 ‘큐에 넣은’ 상태로 설정합니다. 디바이스에서 메시지를 다시 수신할 수 있습니다. 이후에 오류가 발생하지 않도록 하려면 메시지를 수신한 후 1분 이내에 메시지를 완료할 디바이스 측 논리를 구현합니다. 이 1분 시간 제한은 변경할 수 없습니다.

429001 예외 제한

IoT Hub에 대한 요청이 실패하고 429001 ThrottlingException 오류가 표시될 수 있습니다.

요청된 작업의 IoT Hub 제한 한도를 초과하면 이 오류가 발생합니다.

이 오류를 해결하려면 원격 분석 메시지 보내기 시도 메트릭을 위에서 지정한 한도와 비교하여 제한 한도에 도달하는지 확인합니다. ‘제한 오류 수’ 메트릭도 확인할 수 있습니다. 이러한 메트릭에 대한 자세한 내용은 디바이스 원격 분석 메트릭을 참조하세요. 메트릭을 사용하여 IoT 허브를 모니터링하는 방법에 대한 자세한 내용은 IoT Hub 모니터링을 참조하세요.

IoT Hub는 너무 오랜 기간 한도를 위반한 경우에만 429 ThrottlingException을 반환합니다. 이렇게 하면 IoT 허브에 트래픽 버스트가 발생할 때 메시지가 삭제되지 않습니다. 반면 IoT Hub는 작업 제한 속도로 메시지를 처리합니다. 이 경우에 백로그에 너무 많은 트래픽이 있으면 성능이 저하될 수 있습니다. 자세한 내용은 IoT Hub 트래픽 셰이핑을 참조하세요.

할당량 또는 제한 한도에 도달하는 경우 IoT Hub를 스케일 업하는 것이 좋습니다.

500xxx Internal errors

IoT Hub에 대한 요청이 500 및/또는 일종의 "서버 오류"로 시작하는 오류가 발생할 수 있습니다. 몇 가지 가능성은 다음과 같습니다.

  • 500001 ServerError: IoT Hub에 서버 쪽 문제가 발생했습니다.

  • 500008 GenericTimeout: IoT Hub가 시간이 초과되기 전에 연결 요청을 완료할 수 없습니다.

  • ServiceUnavailable(오류 코드 없음): IoT Hub에서 내부 오류가 발생했습니다.

  • InternalServerError(오류 코드 없음): IoT Hub에서 내부 오류가 발생 했습니다.

500xxx 오류 응답에는 여러 가지 원인이 있을 수 있습니다. 모든 경우에서 이 문제는 일시적일 가능성이 높습니다. IoT Hub 팀에서는 SLA를 유지하기 위해 열심히 노력하고 있지만, IoT Hub 노드의 작은 하위 집합에 이따금 일시적인 오류가 발생할 수 있습니다. 디바이스에서 문제가 있는 노드에 연결을 시도하면, 이 오류가 나타납니다.

500xxx 오류를 줄이려면 디바이스에서 다시 시도하세요. 재시도를 자동으로 관리하려면 최신 버전의 Azure IoT SDK를 사용해야 합니다. 일시적인 오류 처리 및 재시도에 대한 모범 사례는 일시적인 오류 처리를 참조하세요.

문제가 지속되면Resource Health 및 Azure 상태를 확인하여 IoT Hub에 알려진 문제가 있는지 확인합니다. 수동 장애 조치(failover) 기능을 사용할 수도 있습니다.

알려진 문제가 없고 문제가 계속되면 추가 조사를 위해 지원팀에 문의하세요.

503003 파티션을 찾을 수 없음

IoT Hub에 대한 요청이 실패하고 503003 PartitionNotFound 오류가 표시될 수 있습니다.

이 오류는 IoT Hub 내부 오류이며 일시적일 수 있습니다. IoT Hub 내부 서버 오류를 참조하세요.

이 오류를 해결하려면 IoT Hub 내부 서버 오류를 참조하세요.

504101 게이트웨이 시간 초과

IoT Hub에서 디바이스에 직접 메서드를 호출하려고 하면 504101 GatewayTimeout 오류와 함께 요청이 실패할 수 있습니다.

IoT Hub에서 오류가 발생하여 시간 초과 전에 직접 메서드가 완료되었는지 확인할 수 없기 때문에 이 오류가 발생합니다. 또는 이전 버전의 Azure IoT C# SDK(<1.19.0)를 사용하는 경우 버그로 인해 디바이스와 IoT Hub 간의 AMQP 링크가 자동으로 삭제될 수 있습니다.

이 오류를 해결하려면 다시 시도하거나 최신 버전의 Azure IOT C# SDK로 업그레이드합니다.