Troubleshooting

Most answers start in the log: run Sync Servers: Show Log, or choose Show Log on an error message.

The log

The Sync Servers log in the Output panel carries the engine's records: connections, transfers, files held back and why, and every failure. Passwords and other secrets are removed before a line is written. VS Code's Set Log Level... on the panel shows more or less detail. Check a line for host names and paths before posting it anywhere.

Problems and what to do

The Sites view says the list of sites cannot be read

sites.json holds something the engine does not accept, often after an edit by hand. Click the row, or Open sites.json on the message, to open the file; the message names the site, the server, the field and its value, such as Site "My Site", server "Production", remoteRoot "example.com/my-site": Must be an absolute path that starts with "/". Fix it, or put back sites.json.bak beside it. The view reloads when the file is saved.

"The host ... was not found", or a host refuses the connection

Check the Host against the FTP or SFTP host your hosting panel shows, and the protocol and port: SFTP usually uses 22, FTPS 21, implicit FTPS 990. Edit Host on the message opens the server in Site Settings, where Test tries the new values before you save them.

A certificate is not accepted

The warning names what is wrong: a certificate issued to another name, signed by itself, from an authority this computer does not trust, expired, or not the one trusted before. When it covers another name for the same server, such as server1.hosting.example.net, connecting to that name keeps full verification. Otherwise compare the SHA-256 fingerprint with the one your host publishes before trusting it. An expired certificate is never trusted: ask your host to renew it, or check this computer's date and time. A trusted certificate is listed on the server's Advanced tab, with Forget Certificate.

"The remote root ... was not found"

The root directory is not where the account sees it; many hosts start an account in its own folder. The message names the folder the account opens in and the folders it holds. Choose Folder on the message lists them so you can pick the right one, then saves it and tests again; Browse... in Site Settings does the same.

The host key of a server changed

The connection stops, showing both fingerprints. Ask your host whether the key really changed. If it did, open the server in Site Settings, choose Forget Host Key, save, and trust the new key on the next connection.

Signing in fails, or the password is asked for again

When the server refuses the sign-in, check the User first: many hosts name FTP accounts in full, such as demo-user@example.com. Sign In Again on the message asks for the user and the password, and offers to save the password once the server accepts it. A saved password is tied to the protocol, host, port and user it was saved for, and is not sent after any of them changes; the password box then says so. Choose Set Password... on the server to save it again. The command line keeps its own passwords, so a password saved there is not known to VS Code.

A saved file is not uploaded

Check, in order: the server's Upload on save is on and the site is saved; syncServers.uploadOnSave.enabled is on; the workspace is trusted; the file is not cloaked and matches no sensitive pattern; and the file did not change on the server too. The log says which it was.

The Explorer shows no marks

Marks show for the active site only, and only after it has been synchronized once. Check the status bar for the active site, and that syncServers.decorations.enabled is on.

Put and Get are missing from the Explorer's menu

They show when the open workspace is inside the active site's local folder. Open the site's folder with Open Site Folder, or run the commands from the Command Palette.

"is not inside the local folder of any site"

The file is outside every site's local folder. Check the site's Local site folder in Site Settings.

A file keeps asking for a decision

It changed locally and on the server since the last sync, or differs with no sync record. Choose Use Local, Use Remote or Mark Synchronized in the preview; Skip leaves it waiting for next time.

Every file shows as changed after a server change

Some servers cannot set file times, or round them. Each side is compared with its own record, so this usually settles after one sync. If not, raise the Time tolerance in the Synchronization category, or compare by checksum.

"is more than" the delete limit

The run would delete more files than the site allows without a check. Type the count when asked, or raise the delete limit in Site Settings if large deletes are normal for the site.

The command line and VS Code show different sites

They read different folders. Check syncServers.configDir in your user settings and SYNC_SERVERS_HOME in the environment VS Code was started from.

The engine's troubleshooting page lists every error code and what to do about it.