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. Live allows only the primary SFTP user, so an extra account is refused on live even when it works on staging.
  8. Git mode makes code read-only. Live is always in Git mode, and new staging and multidev environments start in it too. On an 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 and push to the environment's branch. Or switch staging or a multidev to SFTP mode with the SFTP | Git switch on the Code card on Info; wp-admin and SFTP can then write code there. Live stays read only.
  • If you need a second person to upload files into one folder, add an extra SFTP account on staging with POST /v1/environments/{id}/sftp-accounts. Live answers 409 (live_is_immutable): it allows only the primary SFTP user. 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.