Troubleshooting

Start with sync-servers doctor and sync-servers server test. Most problems show up there with a sentence saying what to do.

First steps

sync-servers doctor checks Node.js, the settings and state folders, the credential store, the terminal, and every site's folder and servers.
sync-servers server test connects, signs in and checks the root directory, step by step.
--debug adds protocol details to the output, with every secret removed. The same details are in the run logs; sync-servers config path shows where.

Connection problems

"The host ftp.example.org was not found": The name does not exist. Compare it, letter by letter, with the FTP or SFTP host your hosting panel shows; it is often not your site's own domain. The host is the name alone: a port goes in --port, so server1.hosting.example.net:21 is written --host server1.hosting.example.net --port 21.
The connection is refused or times out: Check the protocol and port: SFTP usually uses 22, FTPS 21 and implicit FTPS 990. sync-servers site show lists them, and server edit Production --port 2222 changes one. Ports such as 2082, 2083, 2086, 2087, 2095 and 2096 belong to web control panels, not to FTP or SFTP. A firewall between you and the server, or a VPN you are not connected to, looks the same. A slow server may need a longer --timeout.
It works over IPv4 but not IPv6, or the other way round: Set the server's IP version: server edit Production --ip-family 4.
FTP transfers hang after the listing: Only passive mode is supported. The server must allow passive data connections, and its firewall must let them through.
The certificate names another host (E_TLS_CERT): Shared hosting serves many sites from one machine, and its certificate names that machine, such as server1.hosting.example.net, not your domain or an IP address. Run sync-servers server test in a terminal: it shows the certificate and, when it finds a host name the certificate covers that leads to the same machine, offers to connect to it. In a script, the error names that host: sync-servers server edit Production --host server1.hosting.example.net. Your hosting panel usually shows the same name as the FTP host. See Certificates.
The certificate cannot be verified (E_TLS_CERT): The FTPS certificate is not signed by an authority this computer trusts. For a private authority, pass its PEM file with --ca-file. For a self-signed certificate, run server test in a terminal and trust it after comparing its fingerprint with the one your host gives you; a script passes --trust-certificate with that fingerprint. An expired certificate is never trusted: ask the host to renew it, or check this computer's date and time. Never switch to plain FTP to get past this.
The host key does not match (E_HOST_KEY_MISMATCH): The server offered a different SSH host key from the one you trusted. Stop and ask the server's administrator whether the key changed; if it did, check the new fingerprint, then server edit Production --forget-host-key. See Host keys.
An old server offers no algorithm in common: Only modern SSH algorithms are offered. Ask for the server to be updated; if that is not possible, --legacy-algorithms allows older ones, with a warning on every connection.
The remote root was not found (E_REMOTE_ROOT): Many hosting accounts open in their own folder and see it as /, so a path from the control panel, such as /home/<user>/example.com/my-site, does not exist for them. The message names the folder the account opens in and the folders it holds. Run sync-servers server test in a terminal to pick the root from what the server shows; it is saved. In a script, set the root as the account sees it: server edit Production --remote-root /, or the folder below it that holds the site.
The site's folder is hard to find in the list during setup: Setup lists every folder of the folder shown, numbered, with folders whose names start with a dot, such as .cache/, after the others. Hosts often keep a site in a folder such as public_html/, www/ or htdocs/. Type its number to open it, or type its name or path to take it at once; .. goes up a level. With --plain, or when the output is not a terminal, the list has one folder per line.

No password is found (E_AUTH): In a script nothing is asked. Save the password with sync-servers password set, or set SYNC_SERVERS_PASSWORD for the run. In a terminal you are asked when no other source has it.
Asked for the password after editing a server: "The saved password is for another host or user, so it was not sent." A saved password is tied to the protocol, host, port and user it was saved for; after any of them changes, the password is asked for again. Once the server accepts it, you are offered to save it for the new settings. If you did not change the server, check sites.json: someone may have pointed it elsewhere.
"The saved password was saved for another protocol, address or user": The same, in a script, where nobody can be asked. Save the password again with password set, or run server test in a terminal once.
"did not accept the user name or password (530)": Check the user name first: many hosts name FTP accounts in full, as demo-user@example.com, not demo-user. Your hosting panel shows the exact name. In a terminal, server test asks for the user name and password again and saves what the server accepts. Then check the password, and save it again with password set if it changed. A saved password is read only when the server has savePassword on, which password set turns on.
The credential store cannot be used (E_CREDENTIAL_STORE): On Linux the Secret Service needs a running keyring, such as GNOME Keyring or KWallet, which headless machines often lack; use SYNC_SERVERS_PASSWORD there. sync-servers doctor says whether a store is available.
Key sign-in fails: Check --key-path; a key with a passphrase reads it from the credential store, SYNC_SERVERS_KEY_PASSPHRASE, or a question. For the SSH agent, SSH_AUTH_SOCK must point at it; on Windows the OpenSSH agent service must be running.

Time problems

Every file shows as changed after the first sync: Some servers cannot set file times, or keep them to the minute. Records compare each side with its own earlier state, so this usually settles after one sync. If not, raise the time tolerance in the Synchronization category, or switch sync.compare to checksum.
A plain FTP server without MLSD shows no times: Then size alone decides on that side. A file edited without changing its size is not seen as changed there; use sync-servers put for it, or a server that supports MLSD.
A file changed since the preview (E_STALE_ITEM): Someone changed it between the preview and the transfer, so it was skipped. Run the sync again to see its new state.

Case problems

"Another file differs from this name only by case": The server has Logo.png and logo.png, and this computer's file system cannot hold both. Neither is transferred. Rename one on the server, then synchronize again.
"Spelled differently on the other side only by case": The file is Logo.png here and logo.png on the server, as after renaming it by case. A server that ignores case would take the upload and the delete for the same file, so neither runs. Rename it on the server to match, then synchronize again.
"Name is not valid on this system": The name holds a backslash, or a name Windows does not allow: one ending in a dot, containing :, or shaped like a short 8.3 name such as GIT~1. Rename it on the server.

Link problems

"Symbolic link skipped: this site does not follow links": The site's sync.symlinks is skip, the default. To put and get links as the files and folders they point to, run sync-servers site edit --symlinks follow-inside-root, or --symlinks follow for links that lead out of the site too. See Symbolic links.
"Leads out of the site, and this site follows only links inside it": The link points outside the site's folder, and the site is set to follow-inside-root. Set it to follow to synchronize the link, or move what it points to into the site.
"Symbolic link to something that does not exist": What the link points to was moved or deleted. Point the link at it again, or remove the link.
"Leads back into a folder above it": A folder link points at the site's folder, or at a folder that holds the link, so following it would never end. Remove the link, or point it somewhere else.
"Inside a linked folder that is not followed": A folder on one side is a symbolic link that is not followed, so nothing inside it is transferred. Links on the server are never followed. For a link in the local folder, set sync.symlinks to follow it, or replace the link with a real folder.
"Reached through a link that leads out of the site": The site is set to follow, and the file is reached through a link out of the site's folder. A Get or a delete of that row changes the file where it is, outside the site. Uncheck the row to leave it alone.

Error codes

Every error has a stable code, shown with --json and available to programs as SyncError.code.

Error codes and what to do
Code	Means	Do
`E_HOST_KEY_MISMATCH`	The SSH host key differs from the pinned one, or an unknown key was refused with nobody to ask.	Check the fingerprint with the server's administrator; pass `--host-key` in scripts.
`E_TLS_CERT`	The FTPS certificate could not be verified, and nobody accepted it.	Connect to a host it covers, use `--ca-file`, or decide in a terminal with `server test`; scripts pass `--trust-certificate`.
`E_INSECURE_PROTOCOL`	Plain FTP without `allowInsecure`.	Use SFTP or FTPS.
`E_AUTH`	Signing in failed, or no password or passphrase was found.	Save the password, or set `SYNC_SERVERS_PASSWORD`.
`E_CONNECTION`	The connection was refused, reset or dropped.	Check host, port and network; transient failures are retried.
`E_TIMEOUT`	The server stopped answering.	Try again, or raise the timeout.
`E_REMOTE`	The server refused an operation, such as a write without permission.	Check the account's permissions on the server.
`E_REMOTE_ROOT`	The root directory does not exist on the server, or is not a folder.	Set it as the account sees it; the message names the folder the account opens in.
`E_LISTING_LIMIT`	A folder holds more than 100,000 entries.	Cloak it, or narrow the sync to some paths.
`E_PATH_UNSAFE`	A path would leave the site, is not valid here, or is reached through a link the site does not follow.	Rename the file, or see Link problems.
`E_MASS_DELETE`	More deletes than the limit, not confirmed.	Review the preview; confirm, or pass `--allow-mass-delete`.
`E_EMPTY_ROOT`	One side is empty and the plan would delete everything on the other.	Check that the drive is mounted and the root directory is right.
`E_ROOT_DELETE`	Deletes at the top of a server were refused.	Point the server at the site's folder, or set `allowRootDeletes`.
`E_STALE_ITEM`	A file changed between the preview and its transfer.	Synchronize again.
`E_PLAN_INVALID`	A row cannot take that action, or a saved plan no longer matches a fresh scan.	Choose an allowed action, or plan again.
`E_CONFIG_INVALID`	The settings, the sync records or a given value are not valid.	Fix the named field, in `sites.json` with `sync-servers config edit`.
`E_SITE_NOT_FOUND`	No site has that name or id.	List the sites with `sync-servers sites`.
`E_SERVER_NOT_FOUND`	The site has no server with that name or id.	List them with `sync-servers server list`.
`E_CREDENTIAL_STORE`	The credential store failed, or there is none to save to.	Use `SYNC_SERVERS_PASSWORD` instead.
`E_LOCKED`	Another process held the settings lock too long.	Try again.
`E_CANCELLED`	You cancelled.	Nothing; finished files are recorded.

Still stuck

Open an issue on GitHub with the version, the operating system, the protocol and the output of sync-servers doctor. Replace real host names, user names and paths with placeholders such as sftp.example.com and demo-user. For a security problem, follow Reporting a vulnerability instead.