Skip to content
Avaloi

SFTP connection refused

Check the SFTP switch, the allowed IP list, the password expiration, the host and port, and Git mode when an SFTP connection or upload fails.

SFTP and SSH credentials for an environment live on the site's Info tab, under Primary SFTP and SSH user. A refused connection has one of a handful of causes, and a refused upload has one more. The list below finds them in the order they happen most.

What you see

  • Your client says "Connection refused", "Connection timed out", or "Authentication failed".
  • You connect, but an upload to wp-content/plugins or wp-content/themes fails with "Permission denied".
  • You connect with an extra SFTP account and see one folder instead of the whole site.
  • A password that worked last week is refused today.

Check these first

  1. Is SFTP switched on for this environment? SFTP can be switched off per environment, and a connection to an environment with SFTP off is refused before any password is checked. Turn it back on, or call PUT /v1/environments/{id}/sftp-accounts/status.
  2. Host, port, and username. Open the site, then Info, and read the host, port, and username under Primary SFTP and SSH user. Every environment has its own, so staging credentials do not open live. Download the FTP client config file from the same place, or call GET /v1/environments/{id}/ssh/config for the exact connection commands.
  3. The allowed IP list. The Info tab lets you edit the IP allowlist for SFTP and SSH. If your current address is not on it, the connection is refused or times out. Your address changes when you move between home, the office, and a VPN. Read the list with GET /v1/environments/{id}/ssh/allowed-ips.
  4. Password expiration. The Info tab shows the password expiration. An expired password is refused until you rotate it. Choose Show the password to see or rotate it; Avaloi asks for your account password again before it shows a secret, and hides it after a minute.
  5. Rotated credentials. If a teammate rotated the credentials, the old password stopped working at that moment. Open User activity on the site to see who rotated them and when, then read the new password from the Info tab.
  6. Authentication methods. The Info tab lets you set which methods are allowed. If password sign-in is off, you need an SSH key on the environment. Add one with POST /v1/environments/{id}/ssh-keys.
  7. An extra SFTP account sees one folder only. Additional SFTP users each get one folder. If you connect with one of them and cannot reach wp-content, nothing is wrong. Use the primary user for the whole site.
  8. Git mode makes code read-only. On a live environment in Git mode, code folders are read-only, so an upload to wp-content/plugins, wp-content/themes, or any other code folder fails with "Permission denied". Uploads stay writable. The same folders show a lock in the file manager.

Fix it

  • Switch SFTP on, add your current address to the allowlist, or rotate an expired password. Each of these runs as a job and takes effect when the job is done.
  • If you lost the password, rotate it rather than guessing. Rotation gives you a new password and ends the old one.
  • If you need code on a Git mode environment, put the files in your repository, push to main, and deploy. Or switch the environment to classic mode from the Code tab; wp-admin and SFTP can then write code, and you give up the read-only protection.
  • If you need a second person to upload files into one folder, add an extra SFTP account with POST /v1/environments/{id}/sftp-accounts. The password shows once in the response when the job ends within a few seconds. Later it comes from the SFTP credentials reveal, which needs a recent sign-in.

Still stuck

Write to [email protected] with the site name, the environment, the request ID from the API response or the job ID, and what you tried. Add the username, the exact error line from your client, and the address you connect from. Never send the password.

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.