nspanel-lovelace-ui/docs-standalone/troubleshooting.md

Troubleshooting

Config does not load

Symptoms:

• no panel output
• log shows YAML parse error or file missing

Checks:

1. Confirm CONFIG_FILE path.
2. Validate YAML syntax.
3. Ensure required per-panel keys exist: panelRecvTopic, panelSendTopic, locale, timeFormat, dateFormat, screensaver, cards.

MQTT not connected

Symptoms:

• log repeats MQTT connection retry

Checks:

1. Verify mqtt_server, mqtt_port, mqtt_username, mqtt_password.
2. Verify panel publishes on the same topic as panelRecvTopic.
3. Verify payload includes CustomRecv JSON key.

Home Assistant websocket not connected

Symptoms:

• log repeatedly waits for websocket/auth

Checks:

1. Verify home_assistant_address and home_assistant_token.
2. In add-on mode, verify Supervisor token access is available.
3. Confirm HA is reachable from container network.

Card does not open or navigate

Checks:

1. For navigate.<key>, confirm target card has matching key.
2. For cardUnlock, confirm destination and pin are set.
3. Confirm card type is one of the implemented types.

Brightness behaves unexpectedly

Checks:

1. If using entity-based brightness, verify entity state is numeric.
2. Avoid list-based brightness schedules in this rewrite (not supported).
3. Review interaction between sleepTracking, sleepTrackingZones, and sleepOverride.

Useful logs to look for

• Config file not found
• Error while parsing YAML file
• Connected to MQTT Server
• Home Assistant auth OK
• card type ... not implemented
• Not implemented: <button action>