Troubleshooting
Fixes for failed connections, changed host keys, a missing SSH agent, first-launch warnings, unreachable models, sign-in and licence messages, and settings.json.
Start with what the app tells you. Most problems come with a diagnosis on screen: Hop Doctor for connections, the Farabi panel for models, and Settings for the agent and the vault.
A connection fails
The terminal shows a Hop Doctor report instead of a bare error.
- Read the headline and find the hop marked as failed, and the step: DNS, TCP, SSH, Host key or Login.
- Read the evidence under it. It includes the server’s own words where there are any, and what happened to each login method.
- If a fix is offered, check the before → after change and click Apply & retry. For a fix marked Check first, confirm it against your ssh config.
Avoid retrying the same failing login over and over. Each attempt counts towards the server’s MaxAuthTries and tools such as fail2ban, and Hop Doctor never needs another login to diagnose. See Hop Doctor.
Common causes
| Step | Usually means |
|---|---|
| DNS | The name does not resolve here. If a bastion you have open can resolve it, Hop Doctor offers it as a jump host |
| TCP | Nothing listens on that port, a firewall drops the connection, or the address is unreachable from where it was dialled |
| SSH | Something answered that is not SSH, or the two sides share no key exchange method |
| Login | Wrong user, wrong key, a key the agent does not hold, a cancelled passphrase, or a password the server refused |
“Host key has changed”
The server presented a different key from the one you trusted before.
- If you know why (the server was rebuilt, or its keys were rotated), confirm the new fingerprint with its operator, then click Trust the new key.
- If you do not know why, click Cancel and find out before connecting. Something may be intercepting the connection.
See Host keys.
The SSH agent is not found or is empty
Check Settings › Safety › Vault and keys › SSH agent.
| Status | Fix |
|---|---|
| Not found | SSH_AUTH_SOCK is not set for the app. Start your agent, or on Linux make sure it is started for your desktop session rather than only in a shell profile, then restart Gatesys SSH. On Windows, start the OpenSSH Authentication Agent service or Pageant |
| Empty | The agent runs but holds no keys. Load one with ssh-add ~/.ssh/id_ed25519 |
With Pageant, keys cannot be listed, so the app does not report it as empty. See Authentication.
macOS will not open the app
The macOS builds are signed and notarised by Apple, so the first launch only asks whether to open an app downloaded from the internet.
If macOS says the app “cannot be opened”, that it “could not verify” it, or that it “is damaged and can’t be opened”, the file is incomplete or is not one of ours. Delete it and download it again from gatesys.ai.
See Install › macOS.
Windows SmartScreen blocks the installer
On Windows protected your PC, click More info, then Run anyway. See Install › Windows.
The AppImage does nothing
Make it executable with chmod +x Gatesys-SSH-*.AppImage, then run it. If it still does not start, install your distribution’s FUSE 2 package. See Install › Linux.
Farabi cannot reach a model
The Farabi panel says what is missing and links to Settings. Open Settings › Farabi › Model and read the status pill next to Inference provider.
| Status | Fix |
|---|---|
| Offline | The local server is not running or listens elsewhere. Start Ollama, LM Studio or llama.cpp, check the endpoint, and click Test connection |
| Key needed | Paste an API key for the cloud provider and click Save |
| Not installed | Install the CLI (npm install -g @anthropic-ai/claude-code or npm install -g @openai/codex), then click Detect again |
| Sign in needed | Run the CLI once in a terminal and sign in |
Other messages:
- No models listed for Ollama: pull one first, for example
ollama pull qwen3:8b. For LM Studio, load a model; for llama.cpp, start its server with a model file. - A model cannot be picked: it is an embedding-only model. Choose a chat model.
- Set in settings.json — waiting for your approval: the cloud endpoint was set by an edit of settings.json and is not the vendor’s own API. Nothing is sent to it until you click Approve, so approve it only if you set it yourself. See The settings file.
- Codex is not run: Gatesys SSH could not switch off one of its tools or MCP servers, and the message names which. Turn it off in your Codex setup. The app checks again whenever the
codexbinary or~/.codex/config.tomlchanges.
See AI providers.
Farabi shows Get Pro
Farabi’s panel, the providers list or the hooks card shows a Gatesys Pro card with Get Pro when this device has no active Pro licence. Clicking the terminal’s + for a new tab, or Split, shows a smaller one under the button, since more than one terminal per session is Pro. Renew Pro means a licence was active and ended. Click either to open Settings › Account, then check, in order:
- What does the GateSys Pro card say? Free means no licence was activated on this device: click Use my account’s plan if you are signed in to an account with Pro, or enter a licence key. See Activate Gatesys Pro.
- Expired: the trial or the paid period ended, or the licence went 14 days without a check. Subscribe from the billing page (see Billing), or connect to the internet: the app keeps checking on its own, and Pro comes back as soon as a check goes through.
- Ended: the licence was revoked, or this device was removed on gatesys.ai. Activate again.
- Not valid:
license.jsonholds a certificate that does not verify, because it was edited or copied from another device. Activate again.
Every Free feature keeps working in the meantime, terminals already open stay open, and nothing you set up for Pro is removed. See Plans.
Sign-in messages
The Gatesys account card in Settings › Account, and the setup’s Account step, say why a sign-in stopped. Each message has a button to start again and Dismiss, which puts the card back to its buttons. When the browser got as far as coming back, its tab also says how the sign-in ended, with Return to GateSys.
| Message | Code | What to do |
|---|---|---|
| Can’t reach Gatesys | offline, timeout | The account server did not answer, or not within 10 seconds, and the line under it names the server. Check your connection and click Try again. Everything that is not Pro works without it |
| The sign-in link expired | sign_in_timeout | The browser did not come back within 10 minutes. Nothing changed. Click Start again when you are ready |
| Sign-in was cancelled | denied | The sign-in was closed or declined on the web. Nothing changed; click Try again |
| That sign-in didn’t match | state_mismatch | The browser came back with a sign-in this app did not start, such as one from an older tab, and it was ignored. Click Start again and finish in the tab it opens |
| The sign-in expired before it finished | invalid_grant | Gatesys refused the one-time code: it took too long, or it was used already. Click Sign in again |
| Couldn’t sign in | Any other, such as rate_limited or server | The line under it gives the reason, such as Too many tries — wait a moment and try again. Wait a moment and click Try again |
Two more states are not errors:
- Open the sign-in link, while the app waits: the browser did not open. Click Copy sign-in link and open it in a browser on this computer.
- Approve the account server first: settings.json names another account server or sign-in page. Click Use with its name only if you set it yourself. See Another account server.
Clicking Cancel while the app waits shows no message: the card goes back to its buttons. If a sign-in that worked before stops being accepted, the licence card says Your sign-in has ended (unauthorized); sign in again. See Staying signed in.
Licence messages
Activating, checking or deactivating on the GateSys Pro card can fail with:
| Message | Code | What to do |
|---|---|---|
| Pro is active on another computer | seats_exhausted | A Pro plan works on one computer at a time. Click Deactivate this device on the other computer, or remove it on gatesys.ai/account/devices, then activate again. See Seats |
| That licence key is not one Gatesys knows | license_not_found | Check the key for typos. Keys look like GSYS-XXXX-XXXX-XXXX |
| This account has no Pro plan | no_plan | Enter a licence key instead, or subscribe. See Billing |
| That licence was revoked or That licence has expired | license_revoked, license_expired | Renew, or activate with another licence |
| This device is no longer activated | device_not_active | The seat was freed from another device or on gatesys.ai. Activate again |
| Your sign-in has ended | unauthorized | Sign in again, then click Use my account’s plan |
If Gatesys cannot be reached while you deactivate, the licence stays and Remove from this device only appears. See Deactivating while offline.
Pro · offline grace
The daily licence check could not reach Gatesys. Pro keeps working for 14 days from the last successful check, and the pill shows how long is left. Nothing needs doing: the app checks again on its own, and Check now tries straight away. See The daily check and offline grace.
settings.json was not applied
A banner across the top of the window means an edit to ~/.gatesys-ssh/settings.json does not parse or does not match the schema. It names the line and column, and the key where there is one.
- Click Open settings.json in the banner.
- Fix the line it names, for example a missing comma, and save.
The app keeps using the last good settings meanwhile and never overwrites the broken file. An edit that writes a secret into the file, such as an API key or a hook’s signing secret, is refused the same way; keep secrets in the app instead. See The settings file.
A hook does not deliver
The hook’s card says when it last delivered, the last error and when it retries.
- A webhook must answer with a 2xx within 10 seconds, at an
https://address, orhttp://only on this machine. It never follows redirects. Failed batches are retried, up to 10 minutes apart. - A command hook added in settings.json does not run until you click Approve on its card, and asks again after its program or arguments change.
- Paused — hooks send with GateSys Pro: the device has no active Pro licence. See Farabi shows Get Pro.
Send test event sends one event at once and says whether it arrived. See Hooks.
No host facts appear
The facts strip stays empty when the read does not run:
- Settings › Hosts › Host facts › Remember host facts is off.
- The host opted out: host editor › Advanced › Remember facts about this host.
- Metrics polling is off: Settings › Hosts › Monitoring › Metrics polling is
0. - The server refused the metrics sample a channel.
- It is a production host waiting for your answer to Read facts on …? in the strip.
- The host was read less than ten minutes ago.
A watch says it paused or ended
- Text rules pause while a full-screen app such as vim, less or tmux is open, and while output runs faster than 2 MB a second.
- A watch always says why it ended: the shell closed, the connection dropped, metrics polling gave up, the computer slept, or it expired. Watches do not survive quitting the app.
See Watchers.
A tunnel does not reach Running
The card says why the test connection failed, for example db-primary refused 127.0.0.1:5432 — nothing listening?. Check that the service runs on the server and listens where the card says, then choose Stop or Keep it. A remote tunnel that should listen on a non-loopback address needs GatewayPorts yes on the server.
A Safe Change says “Not confirmed”
Keep did not confirm on the server. Click Retry before the time on the chip. If the window runs out, the server puts the old file back by itself. See The safety net.
Updates do not install
Restart to update waits while a Safe Change waits for Keep, and says so. Keep the change, or let its window end, then restart.
Something unclear or wrong? Tell us.