Jump toUpdate content

How to understand event messages

Reviewed on 05 June 2021Published on 05 June 2021

This section shows you the types of message that can be received in IoT Hub Events.

Requirements:

Device messages

Malformed packet or network errors

  • cannot read MQTT header
  • cannot write MQTT packet
  • cannot decode MQTT header
  • failed to unpack message body

Protocol errors

  • unknown MQTT message type: TYPE: TYPE is not a valid MQTT message type.
  • invalid MQTT QoS value: QOS: Valid QoS values are 0, 1 or 2.
  • empty topics are not authorized: It’s not possible to publish or subscribe to an empty topic.

Security errors

  • invalid device certificate: The device certificate is not valid. It may be because the certificate does not match any device or certificate authority, or that the certificate is not the one expected for that device.
  • mutual TLS authentication is required: It’s not possible to connect a Deny Insecure device in an insecure mode (non mTLS).
  • unauthorized topic TOPIC: It’s not possible to publish or subscribe to a topic forbidden by a device filter rule.
  • hub is not ready: It’s not possible to connect to a Hub that is not ready.
  • hub is deleted: It’s not possible to connect/stay connected to a deleted Hub.
  • hub is locked: It’s not possible to connect/stay connected to a locked Hub.
  • device is deleted: It’s not possible to connect/stay connected using a deleted device.
  • device is not enabled: It’s not possible to connect/stay connected using a disabled device.
  • hub product plan has changed: The Hub product plan has been changed and requires a reconnection.
  • device security has changed, requires authentication: Changing the device security requires a reconnection if the security has been upgraded. If device is connected without TLS authentication and the security has been upgrade to Deny Insecure, it will be disconnected.

Custom Certificate Authority and Auto-Provisioning messages

  • certificate common name cannot be empty: The device certificate is signed by the Hub Certificate Authority but its common name field is empty. In this case the object-id is unknown as the device was not found.
  • could not identify device: The device certificate corresponds to a custom Certificate Authority but the device does not exist (and auto-provisioning is disabled). In this case the object-id is unknown as the device was not found.
  • device was auto-provisioned: A new device was created following a sucessful TLS authentication, the message will be of severity info, the object-id will be the one allocated to this new device. The message will also include the following keys:
    • object-name: the device name taken from the client certificate common name.
      • source-address: the IP address and port of the TLS connection that triggered the device creation.
  • service level: "clean session" flag is mandatory to connect to a shared Hub: It’s not possible keep track of the client state over connections when using a shared hub. A clean session must be used on a shared Hub.
  • service level: publishing retained messages is forbidden on a shared Hub: It’s not possible to publish retained messages when using a shared hub.
  • service level: publishing QoS 2 messages is forbidden on a shared Hub: It’s not possible to publish QoS 2 messages when using a shared hub.
  • service level: subscribing with QoS 1-2 is forbidden on a shared Hub: It’s not possible to subscribe using QoS 1-2 when using a shared hub.
  • service level: message payload is too large: See limitations for the maximum allowed messages payload size.

Route messages

S3 route errors

  • "'BUCKET_NAME' s3 bucket write failed. Error HTTP_STATUS_CODE: ERROR_CODE (request-id: REQUEST_ID)": The route failed to write to the specified s3 bucket. BUCKET_NAME is the name of the bucket route attempt to write to, HTTP_STATUS_CODE and ERROR_CODE are standard S3 error codes

Database errors

  • "failed to connect to database. Error ERRNO: ERRMSG": The route could not connect to your database. ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation
  • "failed to prepare 'QUERY' query. Error ERRNO: ERRMSG": The query preparation failed (rejected by PostgreSQL). ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation
  • "failed to execute query. Error ERRNO: ERRMSG": Query execution failed. You will find the payload associated with this query in the field named payload. ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation
See Also