Reference
Troubleshooting
Fixes for the problems people run into most: updates, Windows warnings, missing hosts, and connection or vault errors.
Updates
From 0.2.0 onwards, Synapse checks synapse.maku.au for a new version when it
starts and every six hours, unless you turn this off in Settings >
Updates. A found update is downloaded and its signature checked against the key
built into the app; it only installs when you choose, from the update banner. Automatic
checks fail quietly if you're offline or the server can't be reached; use Check
now in Settings > Updates if you want to see the reason - it explains signature
or connection failures rather than staying silent.
If your version is 0.1.0 (the first early-access release), there was no updater yet - you need to download and install 0.2.0 or later by hand once. From then on, updates arrive in the app.
Installing an update closes and restarts Synapse, so open sessions end - save anything you need first.
Windows SmartScreen warning
Synapse isn't code-signed for Windows yet, so a fresh download can trigger a "Windows protected your PC" SmartScreen warning. This is expected: click More info, then Run anyway to continue. The app's own auto-update signature (which confirms an update came from Maku and hasn't been tampered with) is separate from this Windows code-signing warning, and isn't affected by it.
Saved hosts disappeared after an update
This was a bug fixed in 0.2.5: Synapse could load an older copy of its data at startup and then save over a newer one. It's fixed - the newest copy always loads, an empty host list can never replace a full one, and everything is saved before an update installs - but if you're still missing hosts from before you updated:
- Open Manage hosts.
- Click Import and export (next to the search field).
- Choose Restore hosts from a backup….
- Pick an automatic backup (Synapse takes one at startup and at most once an hour) and choose Add missing hosts or Replace all hosts.
If you use Sync between devices, the same dialog also offers Restore from synced devices, which copies back anything your other devices still have - only missing hosts are added, and nothing is ever deleted by this.
Connection problems
| Message | What's happening |
|---|---|
| Host key changed | The server presented a different key than the one saved from before. Synapse always refuses this connection rather than letting you click through it, because it usually means either the server was reinstalled, or someone is intercepting the connection. If you're sure the server's key changed on purpose (a reinstall, a new host), remove the old entry from your known_hosts file as the dialog describes, then connect again. |
| Authentication failed | None of the methods Synapse tried (a certificate, a saved password, keyboard-interactive, your SSH agent, default key files) were accepted, or the server closed the connection after too many attempts. Check the username, password or key for that host. |
| The private key is encrypted and no passphrase is saved, or couldn't be decrypted (wrong passphrase?) | Add or correct the key's passphrase in the vault. |
| Gave up after N reconnect attempts | Synapse retries automatically up to a limit (5 by default; change it per host or globally in Settings). Use Reconnect on the session to try again. |
Vault and master password
Not by you, and not by Maku - the vault is encrypted with a key derived from it, and there's no back door. The only ways back are the Cloud backup recovery phrase (0.2.6 and later) or re-entering your credentials by hand. Keep your master password, and any recovery phrase, in a password manager.
Typing the wrong master password just shows "Incorrect master password" - there's no limit on attempts and no lockout. If you've genuinely forgotten it, the vault's "Forgot password?" link leads to erasing the vault: every saved password, key, passphrase and API key is deleted and the master password is removed, but your host list itself is kept - you'll just need to enter credentials again as you reconnect.
File transfer errors
SFTP errors are shown close to what the server reports, for example
path: No such file or directory or path: Permission denied. Check
the path and that your account has access to it on the server.
Finding logs for support
Synapse doesn't keep a general diagnostic log file in the released app. If you've turned on the Logs and recordings service, its window has an Open folder button that reveals where session logs, recordings and the AI audit log are stored - useful context to share if you're reporting a problem with a specific session.
Resetting appearance
Settings has a Reset to defaults button, but it only resets the interface and terminal display options (font size, density, spacing, sound) - not your hosts, connection settings, keyboard shortcuts or services.
Still stuck? Contact Maku via maku.au.