Pterodactyl SFTP Connection Refused: How to Fix It

Published on

Pterodactyl SFTP refused? Check the port (2022 by default), SFTP instead of FTP, the name.serverid username, Wings, the firewall, Cloudflare and host keys.

Disk usage and bandwidth cards in a server control panel

You want to upload a world, a plugin or a config file to your Pterodactyl server, and FileZilla, WinSCP or sftp gives up before it even asks for a password: connection refused. That is not a wrong password. Your client reached an address, and nothing there accepted a connection on that port. The checks below start with what any panel user can fix and end with what needs root on the node, with commands for Ubuntu 24.04 and Debian 12. We checked them against the source of Panel 1.15.2 and Wings 1.13.4, current on 30 October 2026.

Quick answer: Pterodactyl's SFTP server is built into Wings and listens on port 2022 by default, not on 21 (FTP) or 22 (the machine's own SSH). Copy the address and username from your server's Settings tab, set the protocol to SFTP and enter that port. The username is your panel username, a dot and the 8-character server ID, such as jochem.1a2b3c4d, and the password is your panel password. If the port still refuses, Wings is not running or listens on another port: check systemctl status wings and ss -ltnp on the node, and restart Wings after you change the SFTP port in the panel. A timeout instead of a refusal points at a firewall or a node domain behind Cloudflare's proxy.

What the Error Tells You

The Linux connect(2) manual describes a refused connection as one that "found no one listening on the remote address". A firewall that silently drops packets gives a timeout instead, and UFW drops by default: its defaults file on Ubuntu 24.04 and Debian 12 sets DEFAULT_INPUT_POLICY="DROP". The wording narrows it down:

You seeMeaningSteps
ssh: connect to host node.example.com port 2022: Connection refused (OpenSSH) or Network error: Connection to “node.example.com” refused (WinSCP)Nothing listens on that port, or a firewall rule rejects it1, 2, 4, 5
Connection timed out or Network error: Connection to “node.example.com” timed outNo answer: a firewall drops it, the address is wrong, or it is Cloudflare3, 6, 7
Access denied (WinSCP) or Permission denied (OpenSSH)Wings answered; the username, password, key or permission is wrong8
WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! or a host key warning in WinSCPThe node's SFTP key differs from the one your client saved9

Space-Node's Minecraft hosting runs on the Pterodactyl panel, so steps 1 to 3 and 8 apply there; if the port still refuses after those, send support the exact error. Steps 4 to 7 and 9 need root on the node.

Step 1: Copy the SFTP Details From the Panel

Open your server in the panel and go to Settings. The SFTP Details box shows a Server Address such as sftp://node.example.com:2022 and a Username such as jochem.1a2b3c4d, with the note "Your SFTP password is the same as the password you use to access this panel." Click a field to copy it instead of typing it over. Three things go wrong here:

  • The address. It is the node's domain and SFTP port from the node settings. Your game address can be another IP or an alias, so do not reuse it.
  • The username. It is your panel username, not your email address, then a dot and the 8-character server ID. Wings checks this format before asking the panel: a name that does not end in a dot and 8 letters or digits is turned away, and Wings logs failed to validate user credentials (invalid format). The long Server ID under Debug Information does not work here.
  • No SFTP Details box. The panel only shows it to users with the SFTP permission. On a server someone shared with you, ask the owner to tick that permission for your subuser under Users.

Step 2: Set SFTP and the Port in Your Client

A refusal often means the client tried FTP or a default port. Common defaults are 21 for FTP and 22 for SFTP, as WordPress's FileZilla guide lists them, and Wings uses neither. Port 22 belongs to the machine's own SSH server: the panel's node form says Wings "does not use the SSHd process on the main physical server", so your panel login fails there.

  • FileZilla: File, Site Manager, New Site. Set Protocol to SFTP, Host to the node's domain and Port to the number from step 1, then enter your username and password.
  • WinSCP: in the Login dialog, set File protocol to SFTP, then fill in Hostname, Port number, Username and Password. WinSCP's help page for this error lists the wrong protocol and "a non-standard port" among the causes.
  • Command line: OpenSSH's sftp takes the port with a capital -P:
sftp -P 2022 jochem.1a2b3c4d@node.example.com

sftp(1) also accepts the panel's address as a URI: sftp sftp://jochem.1a2b3c4d@node.example.com:2022.

Step 3: Test the Port From Your Own Computer

Test the port before you try more passwords. On Windows, in PowerShell (Test-NetConnection):

Test-NetConnection node.example.com -Port 2022

TcpTestSucceeded : True means something accepts connections on that port; RemoteAddress shows the address it tried. On Linux (nc is in the netcat-openbsd package):

nc -vz -w 5 node.example.com 2022

A line with succeeded means the port is open. failed: Connection refused means the node answered and nothing listens: steps 4 and 5. timed out means no answer at all: steps 6 and 7. To see what answers on the port:

ssh-keyscan -t ed25519 -p 2022 node.example.com

Wings uses Go's SSH library without a banner of its own, so it introduces itself as SSH-2.0-Go, which ssh-keyscan prints in a line starting with #. SSH-2.0-OpenSSH there means the machine's own SSH server holds the port, not Wings.

Step 4: Check That Wings Is Running

sudo systemctl status wings
sudo journalctl -u wings -n 100 --no-pager

The SFTP server lives inside the Wings process, so when Wings is stopped or crashing, the port refuses. At startup Wings first prepares every server and only then opens the SFTP port (root.go), so a refusal in the first moments after a restart is normal. Once it is up, Wings logs sftp server listening for connections with the address and its public host key.

If Wings will not start, our Wings node offline guide goes through the causes. If SFTP keeps dropping out for everyone on a node with Wings 1.13.2 or older, update: advisory GHSA-p682-235x-522p (8 October 2026) describes an SFTP request that crashes the daemon, fixed in 1.13.3.

Step 5: Make Wings and the Panel Agree on the Port

sudo ss -ltnp | grep wings
sudo grep -A3 'sftp:' /etc/pterodactyl/config.yml

The first line shows the ports Wings listens on, 8080 and 2022 by default. The second shows bind_address (default 0.0.0.0, every address) and bind_port from config.yml. The SFTP Details box shows the Daemon SFTP Port from Admin, Nodes, your node, Settings, so both must be the same number.

When you change the Daemon SFTP Port, the panel sends it to Wings, which writes it into config.yml (router_system.go). The SFTP listener, however, was opened at startup and stays on the old port until you restart Wings:

sudo systemctl restart wings

If another program already holds the port, Wings logs failed to initialize the sftp server with address already in use and exits, and systemd keeps restarting it. Find the holder with sudo ss -ltnp 'sport = :2022'. The node form warns: "Do not use the same port that you have assigned for your physical server's SSH process." If you moved OpenSSH to 2022, move it again or give Wings another port.

Step 6: Open the Port in the Firewall

sudo ufw status verbose
sudo ufw allow 2022/tcp

Use your own port number if you changed it. Pterodactyl's troubleshooting page lists 2022 as the SFTP port to open and asks for the right NAT rules when the node sits behind a firewall such as pfSense. Check your provider's network firewall too, if it has one, then repeat the step 3 test.

Step 7: Point the Node Domain Straight at the Node

Run hostname -I on the node to see its addresses, then getent hosts node.example.com on your own Linux machine, or look at RemoteAddress in the step 3 test on Windows. The answer should be one of the node's addresses. An address from Cloudflare's IP ranges means the record is proxied: Cloudflare answers proxied records with its own anycast addresses (proxy status) and by default proxies only HTTP and HTTPS on a short list of ports. Port 2022 is not on it. In our test with OpenSSH 9.6 on Ubuntu 24.04, sftp to a proxied hostname on port 2022 ended in Connection timed out.

The fix is a grey cloud (DNS only) on the node's record; the Wings configuration page says: "You are unable to proxy the SFTP port through Cloudflare unless you have their enterprise plan." If you keep the orange cloud for the Wings API on port 8443, the SFTP Details box still shows that proxied name, so SFTP users need the node's IP or a second DNS-only name.

Step 8: When the Login Fails After the Connection Works

Once the port answers, the panel decides who gets in (SftpAuthenticationController.php):

  • The password is your panel password. An SSH key added under Account, SSH Keys also works, with the same username.
  • After five failed logins for a server within a minute, the panel turns new attempts away, even with the right password, until that minute is over (the defaults of Laravel's ThrottlesLogins). Fix a saved password in your client before you retry.
  • Subusers need the SFTP permission. Wings then checks their read, create, update and delete permissions for each action, so a subuser without delete rights cannot delete over SFTP either.
  • The server must be in a normal state. The panel refuses SFTP while a server is suspended, still installing or failed to install, restoring a backup or moving to another node, and while the node is in maintenance mode.

Your client only shows that access was denied. The Wings log on the node has the panel's reason, such as This server is currently suspended and the functionality requested is unavailable.:

sudo grep -i sftp /var/log/pterodactyl/wings.log | tail -n 20

Step 9: Host Key Warnings After Moving Wings

Wings creates its ED25519 SFTP host key on first start, in .sftp inside the node's data directory: /var/lib/pterodactyl/volumes/.sftp/id_ed25519 by default (server.go). A new node, a reinstall or a move without that file means a new key, and clients that saved the old one warn you. WinSCP compares the key on every connection and warns before you send your password; OpenSSH prints WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! with the new fingerprint and stops.

To keep the old key when you move a node, copy that file to the same path on the new machine, with mode 600, and restart Wings there. Wings only generates a key when the file is missing, and it reads the file once, at startup.

To check a new key, print its fingerprint on the node:

ssh-keyscan -t ed25519 -p 2022 127.0.0.1 | ssh-keygen -lf -

The SHA256: value must match the one your client shows. Then remove the old entry; known_hosts files store a port other than 22 as [host]:port (sshd(8)):

ssh-keygen -R "[node.example.com]:2022"

In WinSCP, accept the new key in the warning only after the fingerprints match. A server moved to another node in the panel gets that node's address, so a host key prompt there is expected too.

If It Still Fails

  • Watch the attempts live: sudo systemctl stop wings, then sudo wings --debug, and connect. Debug mode logs validating credentials for SFTP connection for each login. Press Ctrl+C and run sudo systemctl start wings when done.
  • If the node's name also has an IPv6 address, test both with nc -4 -vz -w 5 node.example.com 2022 and nc -6 -vz -w 5 node.example.com 2022. If only IPv6 fails, fix the AAAA record or the IPv6 firewall rules.
  • Wings 1.13.4 drops connections beyond 32 per user on a server, or beyond 16 logins in progress per IP address. max_connections_per_user and max_authenticating_connections_per_ip under system.sftp in config.yml change these limits.
  • Starting over? Our Pterodactyl setup guide for resellers covers panel and Wings. A Space-Node VPS is KVM with full root access, and the Wings install guide says "KVM is guaranteed to work".

FAQ

Can I use FTP or FTPS instead of SFTP? No. Wings runs an SFTP server only, so choose SFTP in FileZilla or WinSCP. An FTP connection to the SFTP port fails.

Can I move SFTP to port 22? The panel accepts any Daemon SFTP Port from 1 to 65535, but the node form warns against the port your machine's own SSH server uses, so 22 only works after you move OpenSSH elsewhere.

Why does SFTP work with the IP but not with the domain? The domain points somewhere else, or Cloudflare proxies it and does not pass port 2022. Connecting by IP skips both, which makes it a quick test; step 7 has the fix.

Do I need my two-factor code for SFTP? No. SFTP checks only your panel password or one of the SSH keys on your account, so use a strong password or a key.

Do my game servers stop when I restart Wings? No. The upgrade guide says running servers "will not be affected". Your SFTP session runs inside Wings, though, so it ends and you connect again.

Sources

All opened on 30 October 2026: