# 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.

Source: https://featherpanel.com/docs/troubleshooting/

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](https://featherpanel.com/docs/panel/web-server/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](https://featherpanel.com/docs/security#client-ips-and-proxy-trust) |
| Schedules and backups never run | Cron runner not running | See [Cron and workers](https://featherpanel.com/docs/panel/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](https://featherpanel.com/docs/panel/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](https://featherpanel.com/docs/panel/web-server/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](https://featherpanel.com/docs/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](https://featherpanel.com/docs/quilld/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](https://featherpanel.com/docs/migrating/pterodactyl).

## Still stuck

Ask in the [MythicalSystems Discord](https://discord.mythical.systems) with your log links, the install method
(Docker or source), your OS and what you already tried. Search the [FAQ](https://featherpanel.com/docs/faq) first.

## Frequently asked questions

### How do I share my logs when asking for help?

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.

### I lost access to the only admin account. What now?

Run featherpanel users on the panel host. It opens an interactive menu that can change a user's password, e-mail or role.