Connection and host-key problems
Connection failures name the stage they failed at, and the stage tells you where to look. Something that fails before authentication is about reachability or identity; something that fails after it is about the account or the services behind it.
Symptoms
- It never reaches the host. The attempt ends at the network stage — refused, timed out, or the name did not resolve.
- The fingerprint dialog appears. A first connection, or a host whose key has changed.
- Authentication is rejected although the address is right.
- The connection succeeds but a capability is missing — no Files, no Terminal, no Host details.
- An established connection drops mid-session.
Checks
1. Read the stage, not just the message. Reachability, host-key verification, authentication and service setup fail differently, and only the first two can be diagnosed without touching the account.
2. For an unreachable host, check reachability outside ShellCanvas — that the address resolves, the port is open, and the SSH service is actually running. ShellCanvas is a client; it cannot make a closed port answer.
3. For a fingerprint prompt, compare the fingerprint out of band. On a first connection, get the expected fingerprint from the host itself or from whoever administers it. For a host you have connected to before, a changed key means something changed: a rebuilt machine, a reinstalled service, a restored image — or a connection that is not reaching the host you think it is. Verification happens before any credential is sent, by design, so a rejected prompt has cost you nothing.
4. For authentication failures, check the method against the host. Confirm the username, and that the host accepts the method you chose — a key the server does not have, or password authentication the server has disabled, both look like a rejection from here. Passphrases are entered per connection and are never stored in a saved host profile.
5. For a missing capability, check what the connection advertises. A capability the provider does not offer is shown as unavailable rather than failing when used; with an adapter connection it means the required methods were not in its catalog. This is a boundary, not a fault.
6. For a drop, look at what survived. Failures are scoped: a lost console does not invalidate the file list, and unsaved editor text is retained. Reconnect rather than retrying the failed operation in place.
Resolution
| Situation | What to do |
|---|---|
| Refused, unreachable or timed out | Fix reachability first — address, port, service, firewall, VPN. Retrying unchanged will fail identically. |
| First-time fingerprint | Verify it out of band, then accept. Accept nothing you could not check. |
| Changed host key | Stop. Confirm with whoever runs the host why it changed, then clear the stored key only after the new one is confirmed genuine. |
| Wrong user or method | Correct the saved host and reconnect. |
| Key needs a passphrase | Enter it when prompted; it is used for the session, not saved. |
| Capability unavailable | Use the capability from a connection that provides it, or add a source that does — see Workspaces and windows. |
| Dropped session | Reconnect from the workspace, then refresh the file list. Transfers restart; they do not resume. See Recover from a dropped connection. |
| Adapter connection fails to start | Check App Manager → Connection adapters → Connection diagnostics and Adapter diagnostics. |
Never work around host-key verification. Deleting trust data to silence a changed-key warning discards the one check that distinguishes your host from someone else's, and it is not a repair.
If the trust store itself is damaged, connections are refused rather than continued unverified. That is deliberate; the fix is to restore or recreate the trust data and re-verify each host, not to bypass the check.
When to report an issue
Report when a connection fails in a way that survives these checks — for example, a host you can reach with another SSH client and not with ShellCanvas, a fingerprint prompt that reappears after you accepted it, or a drop that repeats under a specific action.
Include the ShellCanvas version, your platform, the stage that failed, the visible wording of the error, and the sequence that reproduces it. Include the server's SSH implementation and version if you know it. Exclude host names, addresses, usernames, key material and remote content — a redacted description of the shape of the failure is more useful than a log full of things you must not share.
Related guides
- Make your first connection — the normal path, including fingerprints.
- Saved hosts — profiles, users and authentication methods.
- Recover from a dropped connection — reconnecting cleanly.
- Trust and isolation model — why verification comes first.