Troubleshooting

Something not working in Caret? Start here. This page walks through the problems people run into most often and how to fix them. If none of it helps, email us — we read every message.

Can't connect to a server

A failed connection is almost always one of these:

  • Wrong host, port or username. Double-check the address, the port (usually 22), and the login name. If you can, try the same details from another SSH app on the same network to confirm they work.
  • The server isn't reachable. Make sure your device has internet access, and if the server is on a home or office network, that you're on that network or connected through its VPN. A server on a private network can't be reached from outside unless it has been set up for that.
  • A firewall is blocking SSH. The server's firewall — and, on a cloud server, the provider's security group — must allow SSH on the port you're using.
  • The login was rejected. For password login, re-enter the password. For key login, make sure you imported the matching private key and typed the correct passphrase.
  • "The server's identity changed." Caret warns you when a server's fingerprint no longer matches what it saw before. This can be normal after a server is rebuilt — but if you weren't expecting it, stop and check, because it can also mean the connection isn't safe. Only accept the new identity if you know why it changed.

The connection keeps dropping

  • Check your device's network — switching between Wi-Fi and mobile data, or a weak signal, can interrupt the session.
  • Some servers and routers close idle connections after a while. Reopening the connection brings it back.
  • On the server side, heavy load or a restart will also drop existing sessions.

The Docker tab says it's unavailable

If Caret connects but the Docker screen shows "not available", "no permission", or an error:

  • Docker isn't installed or isn't running on that server. Caret can only manage Docker on servers that already have it.
  • Your account doesn't have permission to use Docker. On many systems, only an administrator — or a user added to the docker group — can talk to Docker. Connect with an account that has that access.
  • On some NAS systems (for example Synology), Docker is set up so that only an administrator account can manage it. Sign in with an admin user and try again.

Tap Retry once you've fixed the cause.

The terminal looks wrong

  • Garbled characters or odd colors usually mean a mismatch with the server's terminal settings. Most servers work out of the box; if yours doesn't, this is typically a server-side setting.
  • The on-screen keys (arrows, Ctrl, Tab, Esc) are on the toolbar above the keyboard — use them for shortcuts and command-line editing.

The monitoring charts are empty

  • The live CPU, memory and other readings come straight from the server while you're connected. If a chart stays empty, the connection may have dropped — reconnect and check.
  • Some detailed statistics need a small helper installed on the server. Caret offers to set this up when it's missing; follow the prompt if you want those extra charts.

Cloud sync isn't working

Sync is optional and uses your own iCloud or Google Drive — Caret has no servers of its own.

  • iCloud: make sure your device is signed in to iCloud and that iCloud Drive is turned on. Sync only works between devices using the same Apple ID.
  • Google Drive: you'll be asked to sign in and set a master password. That password protects your data with end-to-end encryption — it's never uploaded and cannot be recovered if you lose it. If sync won't unlock on a new device, the most likely cause is a mistyped master password.
  • Give a new device a moment after you enable sync — the first download can take a little time.

A purchase didn't unlock, or I switched devices

  • Open the upgrade screen and tap Restore purchases to bring back a lifetime purchase or an active subscription on a new or reset device.
  • Restored purchases are tied to the App Store or Google Play account that made them — use the same account.
  • For refunds or billing questions, contact the App Store or Google Play directly. They handle the payment; Caret never sees your payment details.

Can't connect through a jump host

  • The jump host has to work on its own first. Caret can only reach the final server when every hop in the chain is reachable and its login succeeds.
  • The jump host must be allowed to reach the target server — the target may only accept connections from inside that network.
  • Every hop has its own login. Check the username, key or password for each jump host in the chain.

Port forwarding isn't working

  • Make sure the service is actually running and listening on the server, on the port your tunnel points at.
  • For a local forward, connect to the local address Caret shows (often 127.0.0.1 and the port you chose), not the server's own address.
  • The SSH connection has to stay open for the tunnel to work — if the session drops, the forward stops with it.

File transfers fail (SFTP)

  • Your login needs permission to read or write the folder you're in. Editing a system file usually requires an administrator account.
  • A "permission denied" when uploading or deleting almost always means the account lacks rights to that path — connect with one that has them.

Session recording looks empty

  • Recording stays off until you start it, so a missing log usually means it wasn't running for that session.
  • Logs are saved on your device — review or clear them from the app. They're never uploaded anywhere.

Ask AI isn't answering

  • Check that you entered a valid API key for your chosen provider (for example OpenAI, Anthropic or Google Gemini) and that the key still has quota left with them.
  • Ask AI needs internet access to reach the provider; a request fails if your device is offline or the provider is having trouble.
  • Your key is stored on your device and the request goes straight to the provider — if it's rejected, check the key and your account standing with that provider.

Herdr won't start

  • Make sure herdr is installed on the server and that you can run herdr there over SSH, and that a supported coding agent (Claude Code, Codex, Droid, GitHub Copilot CLI…) is installed too.
  • The Herdr guide walks through the setup, and its own troubleshooting section covers the rest.

Still need help?

If none of the above fixed it, send us a note with:

  • your device and its operating system version,
  • the app version (Settings → About),
  • and what you were doing when the problem happened — plus the exact wording of any error message.

The more detail you give, the faster we can help.