Troubleshooting
Find and fix common FeatherPanel problems. Read the right logs, then work through panel, proxy, websocket, node, SFTP and migration errors with known causes.
On this page
Start with the logs, then find your symptom below. Each section links to the guide with the full details.
Collect logs
| Component | Command |
|---|---|
| All panel containers | cd /var/www/featherpanel && docker compose ps |
| Backend (PHP, cron) | docker compose logs -f backend |
| Frontend | docker compose logs -f frontendv2 |
| Async runner | docker compose logs -f async-runner |
| Upload panel logs | featherpanel logs |
| FeatherWings | journalctl -u featherwings -f |
| Upload node diagnostics | featherwings diagnostics |
| FeatherQuilld | journalctl -u featherquilld -f |
| Installer | /var/www/featherpanel/install.log |
featherpanel logs and featherwings diagnostics upload to the MythicalSystems paste service and print a link. Read
the output before you share it.
Panel
| Symptom | Likely cause | Fix |
|---|---|---|
| 502 Bad Gateway | The frontend container is not running or not healthy yet | docker compose ps; wait for healthy or read the backend log |
| Backend restarts in a loop | Database not ready, wrong credentials in .env, or a failed migration | Read docker compose logs backend; check the MARIADB_* values |
| Page loads, API calls fail | Proxy strips /api or blocks large headers | Use the nginx template as is |
| 413 on upload | Proxy body size limit | Raise client_max_body_size (nginx) or the Caddy/Apache equivalent |
| Wrong IP in audit log or rate limits | Proxy on another host | Set TRUST_PROXY_HEADERS=true; see Security |
| Schedules and backups never run | Cron runner not running | See Cron and workers |
| Locked out of the admin account | Lost password or 2FA device | featherpanel users and edit the user |
| Secrets unreadable after a restore | Different DATABASE_ENCRYPTION_KEY | Restore the key that matches the dump; see Backups |
Console and websockets
The console, live stats and file uploads use a websocket to FeatherWings.
- Mixed content: if the panel uses HTTPS, the node must use HTTPS too. Configure SSL on the node in the panel and
in
/etc/featherpanel/config.yml. - Proxy timeouts: the panel’s own realtime connection needs the WebSocket headers and long read timeouts in your proxy. The Apache template needs the corrections on its page.
- Firewall: port 8080 (or the node’s daemon port) must be reachable from browsers, not only from the panel.
Nodes
| Symptom | Likely cause | Fix |
|---|---|---|
| Node shows offline | Wings not running, wrong FQDN or port, firewall | systemctl status featherwings; test curl -k https://NODE:8080 from the panel host |
| 401 or 403 from the node | Token in config.yml does not match the panel | Re-run featherwings configure with fresh join data |
| SSL errors on the node | Certificate path wrong or expired | Check the ssl block in the node config |
| Server stuck installing | Image pull or install script failure | Read the install log on the server’s console page |
| SFTP refuses login | Wrong username format or port | The username is yourname.xxxxxxxx (your username, a dot and the 8-character server ID); the port is 2022 by default |
More in Wings troubleshooting.
Web hosting
FeatherQuilld problems are mostly DNS or ports. Check that the domain points at the node, that 80 and 443 are free for the proxy, and that the panel can reach the daemon port. See Proxy and DNS.
Migration from Pterodactyl
Run feathercli migrate check first. It reports what the agent can read. Progress is stored in
.migration-progress.json, so you can fix a problem and run the migration again. See the
migration guide.
Still stuck
Ask in the MythicalSystems Discord with your log links, the install method (Docker or source), your OS and what you already tried. Search the FAQ first.
Frequently asked questions
Run featherpanel logs on the panel host and featherwings diagnostics on a node. Both upload to the MythicalSystems paste service and print a link you can post on Discord. Check the output for secrets first.
Run featherpanel users on the panel host. It opens an interactive menu that can change a user's password, e-mail or role.