Troubleshooting
Fixes for the problems people run into most.
Updates and recovery
How the box keeps Epilykos and itself up to date, and rolls back when something goes wrong.
Development guide
How Epilykos is built, how to run it locally, and where to add cards and data sources.
Start with the logs
Before anything else, have a look at Settings → Logs. For a stubborn problem, set How much to log to Debug, make the problem happen again, then download the Diagnostics file. It contains the recent log lines and your settings, with every secret blanked out, so it's safe to share when you ask for help. See Logs.
On Docker, docker compose logs -f shows the same log from the computer itself.
You can't reach the dashboard
| What you see | What to do |
|---|---|
epilykos.local won't open (EpilykosOS) | Try the Pi's IP address from your router instead. If devices on your network can't reach each other at all, turn off the router's "AP isolation" or "client isolation" setting and restart it, or connect the Pi with an Ethernet cable. See Wi-Fi setup. |
| The box can't find your Wi-Fi | The Pi 3B only sees 2.4 GHz networks, and won't see channels 12 or 13 until it knows its country. See Wi-Fi setup. |
| Nothing answers on port 3000 (Docker) | Check that the container is running with docker compose ps, and read docker compose logs. |
EACCES on /app/data or SQLITE_CANTOPEN when it starts | Current images fix this themselves. On an older image, run sudo chown -R 1000:1000 ./data, then docker compose up -d. |
| Live updates stop, with closed before connection is established | Clear the app's old background worker (in your browser's site data for the Epilykos address) and reload. If you use a reverse proxy, check its WebSocket settings. |
Signing in
| What you see | What to do |
|---|---|
| The wizard says Epilykos is already set up, but you never chose a password | Someone else got there first. See If someone else set the password first. |
SETTINGS_PASSWORD in a .env file is ignored (Docker) | The compose file doesn't pass .env into the container. Put the password under environment: instead; see Install with Docker. |
| You've forgotten the password | On EpilykosOS, see Password and factory reset. On Docker, set SETTINGS_PASSWORD under environment:. |
| A two-step code is never accepted | Compare the box's clock with your phone's (the error message shows the box's time). Use a recovery code, or see Locked out of two-step sign-in. |
| Settings won't save | Your session has probably expired; sign out and sign back in. |
| Remote access won't switch on | Your admin password is shorter than 12 characters. Set a longer one; see Security. |
No data, or the wrong data
| What you see | What to do |
|---|---|
| Nothing at all on the dashboard | Check that at least one source is switched on and reading: Settings → Metrics → All metrics shows when each metric last changed. |
| A card shows zeros or nothing | The metric picked on the card has to match exactly what the source writes. |
| The charts are empty | History builds up from the first readings, so give it two or three cycles (60 to 90 seconds). The energy charts and tables also need your metric roles. |
| The grid status card shows nothing | Set the grid status metric to the metric that reads 1 or on while the grid is up. |
| Savings look too low after choosing a generator option | The generator price is still 0; set it in Prices and savings. |
| The generator is missing from charts and costs | Map Generator power and Daily generator energy in Metric roles. |
| Daily totals roll over at the wrong time | The time zone is wrong. On Docker, set TZ or mount /etc/localtime (the first log lines show the active time zone). On EpilykosOS, use Settings → System → Time and storage. |
| The battery percentage jumps around | If your inverter guesses the charge from the voltage, try the battery estimate. |
Modbus
| What you see | Likely cause | What to do |
|---|---|---|
| Connection refused | The IP address or port is wrong | Check that the address answers (ping <ip>) and that port 502 is open. |
| Timeout | The unit ID is wrong | Most inverters use unit ID 1. |
| No data | The registers aren't mapped | Press Load Profile Registers and give every register a metric name. |
| CRC or checksum errors | The baud rate doesn't match | Most inverters use 9600; Voltronic uses 2400. |
There's more on the Modbus page.
Serial ports (RS232, RS-485, wired BMS)
| What you see | What to do |
|---|---|
| No ports are found | Check ls /dev/ttyUSB* and reseat the cable. On Docker, pass the adapter in with devices:; on Docker Desktop, attach it with USB/IP first. |
| Permission denied | On Docker, add dialout under group_add:. Without Docker, run sudo usermod -a -G dialout $USER, then log out and back in. |
| Reads time out | The baud rate is wrong: 2400 for Voltronic, 9600 for SolaX, 19200 for VE.Direct. |
See Install with Docker for passing adapters into the container.
Dongles
| What you see | Likely cause | What to do |
|---|---|---|
| Timeout | Epilykos can't reach the dongle | Check its Wi-Fi signal and ping its IP address. |
| Checksum mismatch | The serial number is wrong | Type it exactly as on the sticker; upper and lower case matter. |
| No data | The wrong profile is selected | Pick the profile for your inverter: a Solarman stick is not a Felicity TCP dongle. |
| No data from a Growatt stick (Docker) | Port 5279 isn't published | Add - "5279:5279" under ports: and run docker compose up -d. |
Bluetooth
| What you see | What to do |
|---|---|
| Bluetooth unavailable: mount the host D-Bus socket | Add - /run/dbus:/run/dbus:ro to the volumes and recreate the container. |
| D-Bus denied access to BlueZ | Add the host's bluetooth group ID under group_add: (getent group bluetooth tells you what it is). On Ubuntu, keep security_opt: apparmor=unconfined too. |
| There's no adapter, or it's switched off | Check bluetoothctl show on the computer; rfkill unblock bluetooth and bluetoothctl power on usually sort it out. |
| A scan finds nothing | Move the adapter closer (Bluetooth reaches about 10 metres), close the battery's phone app, and scan again. On a Raspberry Pi 3, a USB Bluetooth adapter is more reliable than the built-in one. |
| A pack is found but not recognised | Set its type next to the MAC address; see Battery BMS. |
| Bluetooth doesn't work on Docker Desktop | That's expected; see Bluetooth on Docker Desktop. |
MQTT
| What you see | Likely cause | What to do |
|---|---|---|
| Connection refused | The broker isn't running, or the port is wrong | Check systemctl status mosquitto; the usual port is 1883. |
| Authentication fails | The username or password is wrong | Check them against your broker's configuration. |
| No data | Nothing is being published on the topic | Watch the broker with mosquitto_sub -t "#" -v. |
| A value shows up as text | The topic carries a JSON message | Each topic needs to carry a single value; see MQTT. |
Still stuck?
Open an issue on GitHub, and attach the diagnostics file.
Last updated on