Troubleshooting

Common Problems

Problem	Fix
Device not appearing in Home Assistant	Enable MQTT Discovery in HA; verify broker credentials match.
IR codes not learning	Use a 38 kHz receiver; move closer to the sensor.
Bridge shows as offline	Check ESPHome logs (USB or WiFi); verify MQTT broker connectivity.
Serial bridge not detected	Check port permissions (ls -l /dev/ttyUSB*); ensure no other process holds the port.
Automations not triggering	Ensure the device is selected correctly in the trigger, and verify the physical remote code matches the learned code.

MQTT Connection Issues

MQTT credentials mismatch

IR2MQTT reads credentials from /data/options.json (managed by the HA Supervisor). If you changed your MQTT broker password, restart the IR2MQTT add-on — it does not auto-reload credentials.

• Wrong base topic: All topics are prefixed with ir2mqtt/. If you changed the topic prefix in your MQTT broker ACL, make sure it matches.
• Auth error in logs: Look for [MQTT] Connection refused in the IR2MQTT logs. Double-check username and password in the add-on configuration.
• Broker not reachable: If running in standalone Docker mode, ensure the container is on the same Docker network as your broker, or use the host IP instead of localhost.

IR Codes Not Working

TV remotes with Bluetooth mode

Many modern TVs (e.g. Hisense, Samsung) ship with remotes that can operate in both IR and Bluetooth mode. If your remote is currently paired via Bluetooth, the IR LED is inactive and IR2MQTT cannot capture any codes.

How to tell which mode your remote is in: look directly into the IR LED on the remote tip and press a button. There is usually a small SMD status LED right behind it — both colours are very faint, but red means IR mode and blue means Bluetooth.

Switch to IR mode in the TV's settings (look for Remote Control → Disable Bluetooth Remote or similar), then learn the codes. Receiving always works regardless of mode.

• Wrong protocol: If a device doesn't respond to learned codes, try disabling all protocols except the one you expect (e.g. NEC for most TVs) on the Bridge settings page.
• Echo suppression blocking codes: If a button triggers correctly the first time but not immediately after, echo suppression may be too aggressive. Reduce the timeout or disable Ignore Others in the bridge settings.
• RAW codes unreliable: RAW captures are sensitive to timing. Use Smart Learning (multiple presses) to get a more consistent signal. If it still fails, try capturing from a shorter distance.
• Protocol not learning / wrong codes: The carrier frequency may not match your receiver module. RC5 and RC6 use 36 kHz, Sony uses 40 kHz, Dish uses 57.6 kHz — a standard 38 kHz module will struggle outside its range. See the protocol frequency table for the full list. Try holding the remote closer, or fall back to RAW.

Home Assistant Integration

• Entities not created after enabling discovery: HA caches MQTT discovery payloads. Go to Settings → Devices & Services → MQTT and click Re-configure or restart HA.
• Button entity missing: Check that the button has Output (Send) capability enabled.
• Binary sensor always OFF: The button needs Input (Receive) capability enabled, and a signal must be received at least once to register the entity state.
• Device trigger not available in automations: The button needs Event (Trigger) capability enabled.

Bridge / Hardware Issues

Loopback test

Use the Loopback Test card on the Settings page to verify your hardware. It sends a test code and checks if the receiver picks it up — great for confirming TX/RX wiring.

• Bridge discovered but immediately goes offline: Check power supply stability on the ESP32. Brownouts during IR transmission are common with weak USB power.
• Serial bridge port disappears: On Linux, add your user to the dialout group: sudo usermod -aG dialout $USER. Reconnect after re-login.
• Multiple bridges causing cross-talk: Enable Allowed Bridges (Receiving) on devices to restrict which bridge can trigger them, and enable Ignore Others in echo suppression.

Docker / Standalone

• Data not persisting after restart: Ensure /data is mounted as a Docker volume: -v ir2mqtt_data:/data.
• Web UI not reachable: The default port is 8099. Check that the port is exposed: -p 8099:8099.
• options.yaml changes not applied: Restart the container after editing the file — settings are only read on startup.