Troubleshooting

Troubleshooting

Fix startup errors immediately. Once the USB receiver is listening, compare reception over 65 minutes after an antenna or gain change: the transmitter normally sends only about once an hour. Release 0.3.0 logs startup, MQTT connection and a listening summary every 15 minutes in normal mode. See log examples; a scan has no normal heartbeat.

Tip

Before asking for help, note your ha-taggle version, installation method, USB receiver model and exact error text. Replace transmitter IDs with fictional 123456 and leave out passwords and private configuration. Unknown signal details are fine.

Nothing received

Symptom	Possible cause	Next action
No IDs after a healthy 65-minute scan	Antenna position	Move it to a window facing the meter or higher. Use a USB extension to reduce computer noise.
No IDs after a healthy 65-minute scan	Antenna connection or length	Check the connection. Set each dipole side to about 8 cm total metal: roughly 6 cm visible plus metal inside the base (details).
No IDs after a healthy 65-minute scan	Gain too low or overload	Try 49; if reception worsens, return to 40 or lower. Apply the change and restart the scan.
No IDs after a healthy 65-minute scan	Metal lid or wall	Move your receiving antenna to another side of the house. Leave utility equipment in place.
No IDs after a healthy 65-minute scan	Different channel or transmitter type	ha-taggle listens near 922 MHz, not every Taggle channel. Check for NB-IoT on the label. See coverage.
Other IDs heard, yours missing	Weaker signal, different channel, ID error or cellular transmitter	Check the label and antenna placement. Encryption alone does not hide a supported frame's ID. See Finding your meter.
Scan worked, normal reception has no usage	Wrong ID or still scanning	Check meter_ids. Return to normal mode using your installation's instructions.

The dongle won't open

Only one program can use the USB receiver. Stop other SDR software before considering driver changes.

Symptom	Possible cause	Next action
“Device busy” or “usb_claim_interface error”	Another receiver owns it	Stop other SDR add-ons, containers or processes, including a normal ha-taggle receiver before a one-off scan.
Still busy after competing receivers stop	Linux DVB TV driver	The tested Docker image detached it automatically. On Debian/Ubuntu hosts only, follow driver troubleshooting if needed. HA OS users should check add-ons, USB and power, then seek help; these host commands are not an HA OS setup step.
“No supported devices found”	USB mapping or passthrough	Docker: check /dev/bus/usb mapping. VM: pass the device to the VM. HA OS: reconnect the USB receiver and restart Taggle water meter.
“No supported devices found”	Power or cable	Try another port, extension cable or powered hub.
Errors after unplugging	USB disconnected	Replug it. A previously working SDR that disconnects is retried after 2 seconds. If it then stops immediately, retry delay grows up to 60 seconds; see the message below.

No SDR: retry backoff in 0.3.0

No RTL-SDR found or it stopped at once. Check it is plugged in, that a VM has USB passthrough, and that no other SDR program or container is using it. Retrying every 2 s (up to 60 s); this reminder repeats every 10 minutes.

With no samples, retry delay doubles up to 60 seconds, and this receiver reminder is limited to once every 10 minutes. The first delay shown can differ on later retries; driver errors may still appear. A working SDR that drops out initially retries after 2 seconds (SDR stopped; reconnecting in 2 seconds). Check USB connection, VM passthrough and competing SDR apps/containers. MQTT and a heartbeat alone do not establish healthy radio input.

Home Assistant shows nothing

Discovery announces configured meter devices and the enabled neighbourhood device when normal mode connects to MQTT. It does not wait for a radio message or three qualifying neighbours. Values can remain unknown or unavailable while waiting.

Symptom	Possible cause	Next action
No Taggle device under MQTT	No configured ID	Set only your own ID in meter_ids; apply the receiver change.
No Taggle device under MQTT	Still scanning	Add-on: scan_minutes: 0, Save, Start/Restart. Docker: end the scan, then docker compose up -d taggle. Python: stop the scan and run without --scan. Never put scan_minutes in standalone JSON.
No Taggle device under MQTT	MQTT integration missing, discovery disabled, or different broker	Set up MQTT on the same broker, with matching discovery prefix. Check the broker is running. Waiting for radio cannot repair discovery.
Docker cannot connect to MQTT	Wrong host	Use the broker's LAN address. localhost means the receiver container. The example hostname mqtt does not resolve across separate Compose projects.
Docker cannot connect to MQTT	Credentials or listener	Check username/password in the nested mqtt object and the broker's logs/listener. Use the same credentials in Home Assistant.

Readings look wrong

Symptom	Possible cause	Next action
Usage unavailable but diagnostics update	Encryption or temporary counter/sequence discontinuity	Check the encrypted attribute on Last hour where available. A discontinuity needs a consistent new baseline. Usage is not available from confirmed encrypted messages; ID and signal details still work. If uncertain, report what you saw.
Everything for your meter unavailable	No valid message for 3 hours, or receiver/MQTT offline	Check receiver startup, antenna, USB and broker.
Numbers too big or small	Pulses mistaken for litres, or wrong litres per pulse	Calibrate. Check the dial unit: 1 m³ = 1 kL = 1,000 L.
Today lower than expected	Unrecovered intervals	A later frame can recover one missed transmission; longer gaps can remain incomplete. Improve reception.
Dashed chart bars	Unrecovered hourly intervals	Missing values are not estimated. A solid zero mark means observed zero use.
meter_count differs from the dial	Expected	It adds recovered pulse differences. Neither it nor the wrapping raw counter is the dial reading.
Energy has no earlier history	No historical import	Newly recovered intervals enter total_litres at the active litres per pulse. Previously stored intervals are not recalculated or backfilled. See Energy.

Calibration or possible-leak messages

Symptom	Next action
“Not litres yet”	Follow guided calibration, using the full dial reading and matching unit.
Dial entry rejected or excluded	Follow Calibration status. Check digits, unit, photo time, timezone and transmitter ID; delete the mistaken reading, then submit a correction.
Reading waiting for next transmission	Keep receiving so a later frame can bracket it. An old photo without prior counter history needs a fresh reading.
Several pulse sizes fit	Take another reading just after a transmission after more normal water use; do not force an arbitrary factor.
Dial about 1000× off	m³ and kL are equal; L is 1000× smaller. Correct the unit and reading.
Calibrated usage but Meter reading absent	Absolute counter/offset may be ambiguous after a gap. Follow status and enter a fresh reading.
“Counter sequence changed”	Back up state, then reset calibration and take fresh readings as status requests.
Possible leak badge	Check household water use and the physical meter. Read rules and recovery; irrigation and normal night use can trigger it.
Possible leak OFF or unavailable	OFF is no qualifying hint, not proof of no leak. Unavailable follows usage: check reception and supported clear counts.

Neighbourhood row says “unknown”

Possible cause	Next action
Fewer than 3 meters qualify for that group	Normal, especially early in the day. Hearing IDs alone does not qualify them for daily averages.
Just after midnight	Daily figures reset. Wait for at least 6 recovered intervals and the coverage requirement.
Displayed units differ	The card hides its percentage. Neighbour litres use assumed litres per pulse; see the receiver percentage limitation.

Card problems

Symptom	Next action
“Custom element doesn't exist: taggle-card”	Check the manual resource steps or reinstall through HACS, then refresh the browser cache. The resource must serve JavaScript, not a GitHub HTML page.
“Waiting for MQTT entities”	Copy the actual entity IDs into the matching card YAML entries.
“Device lookup failed”	Use an explicit entities: map instead of device:.
“Usage unavailable” before any observation	Card 0.3.0 shows “Waiting for first reading (can take up to an hour)” for a new meter. Confirm startup and discovery; a previously observed meter keeps warnings when reception or usable counts fail.
Old card version still showing	Update ?v= on the resource URL and refresh the browser cache.

Still stuck?

Open an issue. Include what you tried; follow Reporting compatibility for the easy minimum and sharing checklist.

Further reading

• ha-taggle add-on docs: troubleshooting
• RTL-SDR Blog: quick start guide
• Home Assistant: MQTT integration
• FAQ