Skip to main content

Gateway Troubleshooting

Gateway MQTT does not connect​

  1. Verify the server-issued Username/Password/ClientId without rebuilding them.
  2. Check DNS/access to mqtt.airngin.com and the fallback broker.
  3. Do not confuse temporary network failure with confirmed authentication rejection.
  4. Never erase credentials for ordinary connection failure.

Command arrives but Child does not act​

  • was dn/cmd decrypted and validated?
  • is the Child still actively associated with this Gateway?
  • does the Operation have gatewayConfig?
  • is driverKey present in DriverRegistry?
  • is the native bus ready?
  • what status/code is returned by up/cmd/ack/{mid}?

Do not treat MQTT PUBACK as evidence that the Child executed the command.

Child is offline while Gateway is online​

This is valid. Child Shadow should report online=false; do not automatically remove association or retained Shadow.

HTML Live does not work​

  • use the exact four session topics
  • do not append /AES to HTML topics
  • verify temporary credentials are not expired
  • verify session/project/gateway ACL scope
  • never expose Gateway encryptionKey to HTML

Sync is incomplete​

  • inspect sync/check and sync/manifest
  • do not confuse the 8-hour API token with the 30-minute HTML session
  • a malformed snapshot must not replace last-known-good

Analyzer produces no output​

  • does the Driver already emit canonical output? If so, Analyzer is not needed.
  • is Analyzer binding/revision synchronized?
  • does the OperationKey exist in the Device definition?
  • did a resource policy limit trigger?
  • invalid output must be dropped while previous valid state remains intact

Discovery finds nothing​

Discovery is not mandatory for every Driver. Manual onboarding may be the correct path. Scans must not block existing native bus operation.