Troubleshooting SFTP

If you’re having trouble with SFTP, you’re in the right place! We’re here to help you understand common SFTP issues and how to address them.

Clearing known_hosts

On rare occasions, Flywheel will switch out the servers used to manage SFTP. If through troubleshooting we realize that your computer is retaining the IP addresses of servers that are no longer in use, we might ask you to go to make some changes on your machine.

These old IP addresses will be stored in your known_hosts file, a file that is used for SFTP connections. We need to force this file to update so that it can grab the correct IP address.

Instructions for Mac OS

Delete the Local Host File

To remove your “known_hosts” file,  you can do using the following command in your local Terminal window:
cd ~/.ssh
rm known_hosts

Instructions for Windows

If you are on Windows, hosts files are handled on a software by software basis and thus updates to these records are going to be unique to the particular software in use.

Can’t connect to SFTP

The first step here is to be sure to follow our SFTP connection guide. The most common stumbling blocks, though, are as follows:

• Be sure you’re entering your Flywheel username, not your email address. Your username is unique and is the first box you’ll see in your Flywheel profile at app.getflywheel.com/profile.
• Be sure your Flywheel password is correct. A new SFTP password can be set from Profile > Set an SFTP password
• Be sure the server is sftp.flywheelsites.com, and that the port number is 22.
• Also be sure that the protocol is SFTP, not just FTP.

If you’ve checked all the above off the list, then be sure you’re using an FTP client, like Transmit (Mac), Cyberduck (Mac), Filezilla (Mac / Windows), WinSCP (Windows), or Forklift (Mac), just to name some of the most popular options. The main thing is to use an FTP program; you can’t simply visit sftp.flywheelsites.com in a browser.

If your FTP client warns you about host keys when you try to connect, click the appropriate option to ignore the warning and connect anyway.

If your FTP client can’t proceed with the connection because of host keys, try quitting the program and restarting your machine. Sometimes this helps to update old information.

Changes made via SFTP are not displayed on the site

The biggest cause of this issue is browser caching, especially with CSS files. Your browser might not be downloading the newest version of the file, so be sure to flush your browser cache completely, and/or open the page in a private/incognito window. Some browsers, like Chrome, also allow you to force the page to load without cache by using a hard refresh, which is cmd + shift + r on Mac (ctrl + shift + r on Windows). Flushing the server cache from the Advanced tab of the site’s Flywheel Dashboard may also help.

If you’re editing a CSS file, also be sure that the new CSS is specific enough to override the site’s existing CSS.

A new site is not showing in SFTP

In order to avoid database conflicts with concurrent users, SFTP uses a sort of caching, which takes a little time to clear out. This means that, while most of the time a new site should show up in your SFTP directory right away, it is normal for a site to take several minutes to appear there. This is especially common when creating a new site, clone, or Staging site.

If a new site doesn’t seem to be showing up in SFTP right away, then the first thing to try is disconnecting and reconnecting. Once reconnected, use your FTP client’s “refresh” button inside each folder you open.

If that doesn’t work, disconnect from the site completely, and wait at least 10–15 minutes before reconnecting. (All site users who might be connected to SFTP should disconnect as well.) The period of inactivity should flush out the old connection details so the new, updated information will show next time. You may still want to try using the “refresh” button in your FTP client once connected though.

Occasionally get disconnected from SFTP

SFTP will automatically close the connection after several minutes of inactivity. So if you’re not navigating to new directories, or editing/adding/removing files at least somewhat frequently, then there’s a chance the connection may be closed due to inactivity.

While the time limit is high enough that this shouldn’t happen to you if you’re actively working on a site, if you know you’re going to be focused on file editing for a while, the best defense is to use your FTP client’s “refresh” command occasionally, or to make file changes locally and just use FTP to upload the file changes once you’re finished.

This issue may also have to do with the local network or FTP client in use. If you have frequent issues, it may be worth testing other FTP client software and other networks to help narrow down the problem.

“File not found” error message

This could be because the connection was closed, as described in the section above, or it could be that the FTP client or network lost the connection. The best first step here is to try the “refresh” command in your FTP client, then retry saving or uploading the file. If that doesn’t work, then disconnecting and reconnecting is likely the best option.

As with other items on this list, this too may have to do with the local network or FTP client in use, and testing other networks and programs isn’t a bad idea.

Need help?

Sorry, you’re still having problems, but we’re happy to help! Just reach out to our support team and we’ll gladly jump in.