Troubleshooting¶

Common issues¶

"Invalid handler specified" error¶

Cause: Import error in the integration Python files — usually a truncated file copy or stale bytecode cache.

Fix:

1. Check the real traceback in Settings → System → Logs (search for "zigporter").
2. Delete the bytecode cache:

   rm -rf /config/custom_components/zigporter/__pycache__/
   

3. Restart Home Assistant.

Card not appearing after install¶

The card JavaScript is registered when the integration loads, but the browser needs a page refresh to pick it up.

Fix: Refresh the browser with F5 (or Cmd+R on macOS).

"Configuration error" after hard refresh¶

Cause: Home Assistant loads custom card scripts as <script type="module"> (deferred). On hard refresh (Ctrl+Shift+R), the browser bypasses all caches and re-downloads everything — HA's frontend renders cards before the module finishes loading. Since the custom element isn't defined yet, HA shows "Configuration error". This is a known platform limitation that affects all custom cards (Mushroom, Button Card, etc.).

Fix: Use a normal refresh (F5 / Cmd+R) instead of hard refresh. If you've already hard-refreshed, a second normal refresh will resolve it.

Scan times out¶

Large Zigbee networks (50+ devices) can take several minutes to scan. The Z2M coordinator queries each device sequentially.

Fix: Increase the scan timeout in integration options (default: 600s, max: 600s, range: 60–600s).

Typical scan times by network size:

Map shows flat topology (no hops)¶

Cause: ZHA backend often lacks full routing table data.

Options:

• Switch to Zigbee2MQTT backend if available — it provides complete neighbor/LQI tables.
• The ZHA map will still show all devices, just without multi-hop depth.

Stale map after HA restart¶

The integration loads the last cached scan from disk on startup. This is expected behavior — click Scan to capture fresh topology.

If you see an old .gz sidecar file causing issues:

rm /config/custom_components/zigporter/static/*.gz

Wrong backend auto-detected¶

If you have both ZHA and Zigbee2MQTT installed, the integration setup may pick the wrong one.

Fix: During setup (or in options afterward), explicitly select your preferred backend. You can switch between them in Configure without reinstalling.

MQTT not configured error¶

When selecting Zigbee2MQTT as backend, the integration checks that the MQTT integration is set up in Home Assistant.

Fix: Ensure the MQTT integration is configured and connected before adding Zigporter.

Browser cache issues¶

Home Assistant static files can be aggressively cached. If you see stale card behavior after an update:

1. Hard-refresh: Ctrl+F5 / Cmd+Shift+R
2. Clear browser cache for your HA URL
3. Check for stale .gz files in the static directory

Debug logging¶

Enable debug logging for deeper diagnostics:

# configuration.yaml
logger:
  logs:
    custom_components.zigporter: debug

Restart HA, then check Settings → System → Logs for detailed scan progress and timing information.

Getting help¶

• GitHub Issues — bug reports and feature requests
• Check existing issues before filing — your problem may already be tracked