Wings troubleshooting

Fix common FeatherWings problems. Node shown offline, console not connecting, SFTP refused, Docker errors, and how to collect a diagnostics report.

On this page

Start with the logs

systemctl status featherwings
journalctl -u featherwings -n 200 --no-pager

For more detail, stop the service and run Wings in the foreground with debug logging:

sudo systemctl stop featherwings
sudo featherwings --debug

Diagnostics report

sudo featherwings diagnostics

It collects the Wings and Docker versions, the relevant parts of your configuration, Docker’s debug output, the running containers and the latest log lines (--log-lines). It asks whether to include your panel endpoints and logs, offers to show you the report, and only uploads it to pastes.mythicalsystems.org when you confirm. Share the link in a support request.

Common problems

Symptom	Check
Node is red in the panel	Is `featherwings` running? Can the panel reach `https://<node fqdn>:8080`? Is the port open in the node firewall and any cloud firewall?
Panel works, console stays on “connecting”	The browser connects to Wings directly. The node FQDN must resolve for users, and with an HTTPS panel the node needs a valid certificate too, or the browser blocks the websocket.
Certificate errors	Renew with `certbot renew`; the renewal hook should restart `featherwings`. See SSL.
SFTP connection refused	Port `2022` closed, or another SSH service bound to it. Check `system.sftp.bind_port`.
Server will not start	Read the server console and `journalctl -u featherwings`. Docker errors such as port in use or pull failures show there.
“permission denied” on server files	Files changed by hand as root. Restart the server: Wings chowns the server directory before every boot.
Docker missing or wrong package	Wings needs `docker-ce` from Docker’s repository. Remove `docker.io` first.

See also the general troubleshooting page.