Troubleshooting

This guide covers common issues with the Exaviz Home Assistant PoE Plugin and their solutions.

Installation Issues

Integration not appearing after HACS install

Symptoms: You installed the plugin via HACS but “Exaviz” doesn’t appear when searching for integrations in Settings > Devices & Services.

Solutions:

1. Restart Home Assistant – HACS installations require a full restart:

   • Go to Settings > System > Restart
   • Wait for Home Assistant to fully restart (this may take a few minutes)

2. Clear browser cache – Hard refresh your browser:

   • Windows/Linux: Ctrl+Shift+R
   • Mac: Cmd+Shift+R

3. Verify installation – Check that the integration files are in place:

   ls ~/.homeassistant/custom_components/exaviz/
   

   You should see Python files (__init__.py, coordinator.py, sensor.py, etc.) and a manifest.json.

4. Check Home Assistant logs for errors:

   • Go to Settings > System > Logs
   • Search for “exaviz” to find related messages

Custom card not loading

Symptoms: The PoE Port Card shows a blank area or “Custom element doesn’t exist” error.

Solutions:

1. Verify the Lovelace resource is registered:

   • Go to Settings > Dashboards > Resources (three-dot menu)
   • Look for an entry pointing to exaviz-cards.js
   • On Home Assistant 2024.12+, the integration auto-registers the resource at /exaviz_static/exaviz-cards.js. If it’s missing, add it manually:
     • URL: /exaviz_static/exaviz-cards.js
     • Type: JavaScript Module
   • On older HA versions, the auto-registration may not work. Add the resource manually with the URL above, or copy the JS file to your www/ folder and use /local/community/exaviz/exaviz-cards.js instead.

2. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)

3. Check browser console for JavaScript errors:

   • Open browser Developer Tools (F12)
   • Look at the Console tab for errors mentioning “exaviz”

Integration loads but no entities or card appear (Docker)

Symptoms: The Exaviz integration is listed in Settings > Devices & Services, but:

• No entities are created (no sensors, switches, or buttons)
• The custom Exaviz PoE card doesn’t appear when searching “Add Card”
• Home Assistant logs show only a “prerequisites not met” warning and nothing else from Exaviz – no errors, no “frontend cards registered” message

Cause: The docker-compose.yml is missing the required volume mounts and/or device passthrough for PoE hardware. The integration config flow can detect the board type using minimal information, but at startup the coordinator cannot reach the PoE hardware and fails silently. Because the integration never fully initializes, the frontend card JS is never registered.

A common version of this problem is a docker-compose.yml that only has ./config:/config – which is enough for Home Assistant itself but not for the Exaviz integration.

How to diagnose:

1. Enable debug logging by adding this to configuration.yaml:

   logger:
     default: info
     logs:
       custom_components.exaviz: debug
   

2. Restart Home Assistant and check the logs. A working installation will show:

   DEBUG [custom_components.exaviz.coordinator] Finished fetching exaviz data ...
   INFO  [custom_components.exaviz] Exaviz frontend cards registered at /exaviz_static/exaviz-cards.js
   

   If you only see the “prerequisites not met” warning and nothing after it, the required Docker mounts are missing.

Fix: Update your docker-compose.yml to include all required mounts. See the Installation Guide for complete, copy-paste-ready examples for each board type.

Required mounts summary:

After updating the compose file, recreate the container:

docker compose up -d   # Recreates container with new mounts

Board type shows “Unknown” (Docker installations)

Symptoms: The integration title shows “Exaviz Unknown” instead of “Exaviz Cruiser” or “Exaviz Interceptor”, or the board_type attribute on sensor.board_status shows unknown.

Explanation: The plugin detects the board type using a 3-tier fallback chain. In Docker environments, some detection paths may not work without the correct volume mounts.

Detection tiers and Docker requirements:

Solutions:

1. Ensure /boot/firmware/config.txt is mounted – This is the most reliable detection path in Docker. Add this to your docker-compose.yml volumes:

   - /boot/firmware/config.txt:/boot/firmware/config.txt:ro
   

2. Restart HA after fixing mounts – After updating docker-compose.yml, run:

   docker compose up -d   # Recreates container with new mounts
   

   The integration automatically updates its title from “Unknown” to the correct board name on the next startup.

3. Docker resolves /dev/pse symlinks – On Cruiser boards, /dev/pse is a udev symlink to /dev/ttyAMA3. Docker’s device passthrough resolves this symlink, so the device appears as /dev/ttyAMA3 inside the container. The plugin checks both paths automatically, but Tier 2 (config.txt) is faster and preferred.

See the Installation Guide for the recommended docker-compose.yml with all required mounts.

Entity Issues

“Entity not found” in dashboard cards

Symptoms: A card row shows a yellow “Entity not found” warning.

Solutions:

1. Verify entity IDs – The integration uses these entity IDs:

   • sensor.board_status (not sensor.exaviz_board_status)
   • sensor.board_temperature
   • sensor.onboard_portN_current (Cruiser built-in ports, where N = 0-7)
   • sensor.addon_0_portN_current (Interceptor first PoE board / Cruiser add-on)
   • sensor.addon_1_portN_current (Interceptor second PoE board)

2. Check the integration is loaded:

   • Go to Settings > Devices & Services
   • Look for “Exaviz PoE” in the configured integrations
   • If it shows an error, try removing and re-adding it

3. Restart Home Assistant – Some entities only appear after a restart

4. Check Developer Tools:

   • Go to Developer Tools > States
   • Search for “board_status” or “exaviz”
   • Verify the entity exists and has a state

Missing attributes in Board Information card

Symptoms: Some rows in the Board Information card show a dash (–) instead of a value.

Explanation: This is normal behavior. Not all attributes are available on all boards:

If you see dashes for attributes that should be present, restart Home Assistant. Board information is gathered once at startup.

Temperature sensor showing “unavailable”

Symptoms: The sensor.board_temperature entity shows “unavailable” or no value.

Solutions:

1. Check thermal zone access:

   cat /sys/class/thermal/thermal_zone0/temp
   

   This should return a number (e.g., 55000 for 55.0 degrees Celsius).

2. If running in Docker, ensure the container has access:

   • Mount /sys/class/thermal into the container
   • Or run with --privileged

PoE Control Issues

Port won’t enable/disable from the dashboard

Symptoms: Clicking the toggle switch on a PoE port doesn’t change its state, or the state changes briefly then reverts.

Solutions:

1. Check permissions – PoE control requires root access to hardware interfaces. If running Home Assistant in Docker, ensure the container has the necessary privileges.

2. Verify PoE hardware is working from the command line:

   # Cruiser
   head -20 /dev/pse
   # Interceptor
   head -20 /proc/pse
   

   This should show port status information. If the file doesn’t exist, confirm exaviz-dkms is installed (and exaviz-pse-dkms on Interceptor boards).

3. Check the HA log for control errors:

   • Go to Settings > System > Logs
   • Look for messages containing “exaviz” or “poe”

Port shows “empty” but a device is connected

Symptoms: A PoE port indicator is gray (empty) even though a powered device is connected.

Possible Causes:

1. Device is not PoE-powered – The device may be using its own power supply instead of PoE
2. Cable issue – The Interceptor PoE Board requires 8-wire cables (Mode B). 4-wire cables will not deliver PoE power. See PoE Board FAQ
3. Port is in backoff state – On Interceptor boards, an enabled port with no PoE device shows as “empty” (the IP808AR controller is waiting for a valid PoE signature)

Port is active but shows “Unknown” manufacturer and “Not assigned” IP

Symptoms: A PoE port is green (active, delivering power) and shows real power consumption, but the port details display:

• Manufacturer: Unknown
• IP Address: Not assigned

Explanation: The plugin discovers connected devices by looking up their IP and MAC addresses in the system’s ARP table. If the device has no ARP entry on the port’s subnet, the plugin cannot identify it.

Common causes:

1. Device has a static IP on a different subnet. Each PoE port is assigned its own subnet by exaviz-netplan (e.g., poe3 uses 10.100.3.0/24). If the device has a static IP like 192.168.1.100, it won’t communicate on the 10.100.3.x subnet and no ARP entry is created. The device still receives PoE power because power delivery is independent of IP networking.

2. Device hasn’t completed DHCP. Some devices take time to request an address after being powered on. Wait 30-60 seconds and check again.

3. dnsmasq (DHCP server) isn’t running or isn’t configured for the port. Verify:

   systemctl status dnsmasq
   cat /etc/dnsmasq.d/00-exaviz-dhcp-server-interfaces.conf
   

   You should see a dhcp-range entry for each poe* interface.

Fix for static IP devices: Configure the device to use DHCP, or set its static IP to an address within the port’s subnet (e.g., 10.100.3.50 for poe3). After the device obtains or is assigned an IP on the correct subnet, the plugin will automatically discover its MAC address, manufacturer, and IP on the next poll.

Difference between “empty” and “disabled”

An “empty” port is still enabled and will automatically power a PoE device when one is connected. A “disabled” port will not provide power until re-enabled.

Update Issues

Changes not appearing after update

Symptoms: You updated the plugin but the dashboard still shows old behavior.

Solutions:

1. Restart Home Assistant after every update
2. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
3. Clear browser cache if a hard refresh doesn’t work:
   • Open browser settings
   • Clear cached images and files
   • Reload the dashboard

Diagnostic Information

Gathering Support Information

If you need to report an issue, gather this information:

1. Home Assistant version: Settings > About
2. Plugin version: HACS > Integrations > Exaviz PoE Plugin
3. Board type and OS:

   cat /proc/device-tree/model
   cat /etc/os-release
   

4. PoE status:

   head -30 /proc/pse
   

5. Home Assistant logs: Settings > System > Logs (filter for “exaviz”)

Getting Help

If the above solutions don’t resolve your issue:

1. Gather the diagnostic information listed above
2. Note the specific symptoms and when they started
3. Contact support@exaviz.com with:
   • Diagnostic output
   • Description of the issue
   • Steps you’ve already tried

Last modified February 25, 2026