Troubleshooting

Running into issues? This guide covers the most common problems and how to resolve them. For quick answers to frequently asked questions, see the FAQ page.

Backend Won’t Start

Check the service status


sudo systemctl status smart-panel

View recent logs


sudo journalctl -u smart-panel -b --no-pager -n 50

Common causes

Symptom	Likely Cause	Fix
`EADDRINUSE` error	Port 3000 already in use	Stop the conflicting service or change the port in `config.yaml`
`SQLITE_CANTOPEN`	Database file permissions	Run `sudo chown -R pi:pi /var/lib/smart-panel/data`
`JWT secret` error	Missing `FB_TOKEN_SECRET`	Set the environment variable or add it to your `.env` file
Migration errors	Corrupted database after crash	Restore from backup or delete `database.sqlite` to start fresh

Deleting the database will erase all your devices, pages, and settings. Always try restoring from a backup first. See the Updating & Backup guide for backup instructions.

Display App Won’t Start

The panel display runs as a separate service using flutter-pi.

Check service status


sudo systemctl status smart-panel-display

View display logs


sudo journalctl -u smart-panel-display -b --no-pager -n 50

Common causes

Symptom	Likely Cause	Fix
Black screen	Display service not running	`sudo systemctl start smart-panel-display`
`DRM` or `KMS` error	Missing GPU driver	Ensure `dtoverlay=vc4-kms-v3d` is in `/boot/config.txt`
Touch not working	Wrong touch driver	Check your display’s documentation for the correct overlay
Wrong orientation	Display rotation	Add `display_rotate=X` to `/boot/config.txt` (0, 1, 2, or 3)

Can’t Access the Admin UI

If you can’t reach http://smart-panel.local:3000 in your browser:

Check the backend is running: sudo systemctl status smart-panel
Try the IP address directly: Find it with hostname -I on the device, then visit http://<ip>:3000
Check firewall rules: Ensure port 3000 is open — sudo ufw status (if UFW is active)
Verify mDNS: .local domains require mDNS support. See the Network Requirements page

Devices Not Showing Up

Plugin-synced devices (Home Assistant, Shelly)

Home Assistant: Verify the API key and hostname in your config.yaml. The token must be a valid long-lived access token.
Shelly: Ensure mDNS is enabled and Shelly devices are on the same network subnet. Check the Network Requirements page for details.

Manually created devices

Make sure you selected the correct plugin type when creating the device.
Check that the device has at least one channel configured.

Check plugin logs


sudo journalctl -u smart-panel -b | grep -i "plugin\|device\|discovery"

WebSocket Connection Issues

The panel display communicates with the backend over WebSocket. If the display shows stale data or a connection indicator:

Verify the backend is reachable from the display device
Check for proxy interference — reverse proxies must be configured to forward WebSocket upgrades
Restart both services:


sudo systemctl restart smart-panel
sudo systemctl restart smart-panel-display

Docker-Specific Issues

Container keeps restarting


docker compose logs --tail 50 smart-panel

Look for migration errors or missing environment variables.

Health check failing


docker inspect --format='{{.State.Health.Status}}' smart-panel

If the health check reports unhealthy, the backend may be stuck. Restart the container:


docker compose restart smart-panel

Permission issues with volumes

If the container can’t write to the data volume:


docker compose down
docker run --rm -v smart-panel-data:/data alpine chown -R 1000:1000 /data
docker compose up -d

Performance Issues

High CPU usage

Check if a plugin is stuck in a reconnection loop (look for repeated connection errors in logs)
Reduce the number of enabled plugins if running on limited hardware

High memory usage

SQLite can consume memory with large datasets. Consider enabling InfluxDB for time-series data
Restart the backend to free memory: sudo systemctl restart smart-panel

Captive Portal Not Appearing

The captive portal provides first-time WiFi configuration on Raspbian image installs. If it doesn’t appear:

Check service status


sudo systemctl status smart-panel-portal

View portal logs


sudo journalctl -u smart-panel-portal -n 50

Common causes

Symptom	Likely Cause	Fix
No WiFi device listed	WiFi adapter not detected	Run `nmcli device` — you should see a `wifi` device. Check `rfkill list` for blocks
Portal never starts	WiFi already configured	Check if `/var/lib/smart-panel/.wifi-configured` exists — remove it and restart the portal service
Portal starts after long delay	Boot config was applied	If `/var/lib/smart-panel/.boot-config.applied` exists, the portal waits 30s for a network connection before starting
Portal not available at all	Wrong installation method	The captive portal is only available on Raspbian image installs, not script-based installs

If you need to force the captive portal to reappear, delete the WiFi marker file and restart the service: sudo rm /var/lib/smart-panel/.wifi-configured && sudo systemctl restart smart-panel-portal

WiFi Keeps Disconnecting / Portal Restarts

The WiFi watchdog service monitors connectivity and re-activates the captive portal after 5 minutes of WiFi failure.

Check watchdog logs


sudo journalctl -u smart-panel-wifi-watchdog -n 50

Check WiFi signal strength


nmcli device wifi list

Common causes

Symptom	Likely Cause	Fix
Portal keeps reappearing	Weak WiFi signal	Move the panel closer to the access point or use a WiFi extender
Repeated disconnections	Wrong WiFi password	Wait for the watchdog to restart the portal, or power cycle the device and re-enter credentials
Watchdog not triggering	Ethernet is connected	The watchdog won’t trigger when the device is reachable via ethernet

InfluxDB Not Available Warning

If you see a warning about InfluxDB not being available, this is expected behavior when InfluxDB is not installed.

What still works without InfluxDB

Device control and real-time updates work normally
Smart Panel falls back to in-memory storage automatically
Only historical charts and time-series data are affected

Installing InfluxDB later

If you want to enable historical data storage, see the Installation Guide for InfluxDB setup instructions.

Configuring storage

Once InfluxDB is installed, configure the connection in the Admin UI under Settings → Storage Module.

InfluxDB is optional. Smart Panel is fully functional without it — you only need it if you want historical charts and time-series data.

Factory Reset

If nothing else works, you can perform a full factory reset. This erases all data and returns the panel to its initial state.

This will delete all devices, dashboards, users, and settings. This action cannot be undone.

The data location depends on your installation method:

Installation Method	Data Location
One-liner script or npm global	`/var/lib/smart-panel/`
Manual tarball	`/var/smart-panel/`
Docker	Inside the `smart-panel-data` Docker volume


# Stop services
sudo systemctl stop smart-panel smart-panel-display
 
# Delete data (adjust path for your install method)
sudo rm /var/lib/smart-panel/config/config.yaml
sudo rm /var/lib/smart-panel/data/database.sqlite
 
# Restart — onboarding will begin fresh
sudo systemctl start smart-panel smart-panel-display

For Docker:


docker compose down -v
docker compose up -d

Still Stuck?

GitHub Discussions — ask the community
Report an issue — file a bug report
Join our Discord — get real-time help