# MQTT Connection Troubleshooting

### Step 1: Credential format

* **Username/password** must be **alphanumeric only** (A–Z, a–z, 0–9), with no spaces or special characters.
* If special characters were used before, update **both** the broker and the device to a new alphanumeric pair.

### Step 2: Confirm the MQTT broker

1. In HA: **Settings → Devices & Services → Add Integration → search “MQTT” → Configure**.<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FZevtAQEqr28cDWr3pirX%2Fimage.png?alt=media&#x26;token=f9e2afeb-030a-4ce6-8335-060b7cc0a349" alt=""><figcaption></figcaption></figure>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2Fm8DPWszpu1GrofrdIIsX%2Fimage.png?alt=media&#x26;token=0753507e-ee18-4834-a3e4-d566779b5d59" alt=""><figcaption></figcaption></figure>
2. Success indicates the **Broker IP, port, and credentials** are correct.<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FdoBy8ea0SYZ0b9bdTxL5%2Fimage.png?alt=media&#x26;token=fe986d60-8537-4cb6-a329-ae9e57f8666d" alt=""><figcaption></figcaption></figure>
3. On failure:
   * **HA OS**: install and enable **Mosquitto broker** from the **Add-on Store**;
   * Other setups: ensure Mosquitto is running and listening on **1883** (when TLS is off).

### Step 3: Verify network connectivity (device ↔ HA)

1. Add the **Ping (ICMP)** integration in HA and enter the **LinknLink device IP**;<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FcoxeJnFR84Fkpcvzfjqq%2Fimage.png?alt=media&#x26;token=27b970dd-1fd3-43d9-a9cc-9abc715a5936" alt=""><figcaption></figcaption></figure>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FRec2ayxxolmuYBTgFtIE%2Fimage.png?alt=media&#x26;token=ac9fdb87-be60-41cc-8171-6cedd337c1f3" alt=""><figcaption></figcaption></figure>
2. **connected** means same LAN/reachable;<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2F1hFa4PfBbLDWUkhv8fMv%2Fimage.png?alt=media&#x26;token=e3ce8acd-ec2f-44df-8862-244e8b64c294" alt=""><figcaption></figcaption></figure>
3. If it fails: check different subnets/VLANs, **AP isolation/guest network**, or router/firewall rules blocking internal traffic.

### Step 4: Enter MQTT settings on the LinknLink device by using LinknLink App

* **Broker IP**, **port (1883 by default)**, **username/password**;
* Save and Check HA MQTT integration device list

### Step 5: Confirm HA receives messages

1. Open **Developer Tools → MQTT** (or the MQTT integration’s **Listen to a topic**);<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FMONNsjAEBdDPRIebQ1mV%2Fimage.png?alt=media&#x26;token=e15f7833-1de2-45ce-9e66-584730044a0c" alt=""><figcaption></figcaption></figure>
2. In **Topic**, enter **`home/#`** → **Start listening**;<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FzeUTSxWbAS5gHbJnvZLN%2Fimage.png?alt=media&#x26;token=cc4b84b0-e46e-491a-bbef-f0edf5a33395" alt=""><figcaption></figcaption></figure>
3. If you see topics/payloads from the device, the connection and messaging are good.

### Step 6: Deep-dive with MQTT Explorer (optional)

1. Download **MQTT Explorer** from [**https://mqtt-explorer.com/**](https://mqtt-explorer.com/);
2. In **Connections**, add a profile with name, **Host** (broker IP), **Port** (usually **1883**), and credentials;<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FKv8pILF1Y3shgLsWaaqs%2Fimage.png?alt=media&#x26;token=b7289e43-d454-430b-a6a7-3092f0d12096" alt=""><figcaption></figcaption></figure>
3. **Save → Connect** to browse the full topic tree for easier troubleshooting.<br>

   <figure><img src="https://3747235627-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcvOpEUD8lrOqQMMrU7u7%2Fuploads%2FWk3mlzCXXtBaBiYEzKWa%2Fimage.png?alt=media&#x26;token=e1ebb782-f0e5-4225-b6a9-ec5c4173ddbf" alt=""><figcaption></figcaption></figure>

> Once these checks pass, the LinknLink device should connect to MQTT without issues.