Mac SSH connection problems: what to check first

Connection timed out: check the route

First confirm the destination and port, then whether the host requires a VPN, private network or allowlisted source address. A timeout does not tell you which network device dropped the traffic. Ask the administrator to check the route and applicable access rules.

Avoid “fixing” this by broadly opening a firewall or exposing a private SSH service to the internet. Restore the intended access path instead.

Connection refused: check the service and port

A refusal usually means the destination or a network intermediary actively rejected the connection. Check that you have the right host and SSH port, and ask the administrator whether SSH is listening there.

A browser reaching the website on the same domain does not prove that the SSH port is open. Web and SSH services can have different routes and policies.

Permission denied: check the account and authentication

Verify the remote username, the configured key or password method, and whether the account is allowed to log in. If using a key, confirm you selected the intended private key and that the corresponding public key is authorized on the server.

Check the server policy rather than cycling through passwords. An account may require a bastion, additional authentication or a different login identity. Never send your private key or password to a public support thread.

Host identification changed: stop and verify

Do not disable host checking to make the warning disappear. Contact the administrator through a trusted channel and compare the new fingerprint. A rebuild can legitimately change a key; an unexpected host or intercepted route can also cause a mismatch.

Only update the stored trust record after the change is independently confirmed. Deleting every known-host entry erases unrelated trust information and is not a sensible first step.

Use a controlled Terminal comparison

Try the same destination, port and account in Terminal and the graphical client. OpenSSH’s -v option adds connection diagnostics; the manual explains the output controls: https://man.openbsd.org/ssh. Use the correct key option as needed.

ssh -v -p 2222 user@server.example.com

Interpret the comparison carefully

If both attempts fail similarly, investigate the network or server configuration first. If Terminal works and Docklark does not, compare the saved host, port, account and authentication settings. Terminal may also be using configuration or an agent that another client is not using identically.

For Docklark support, record the app version, Mac chip and macOS version, error category, direct or JumpServer route, and minimal reproduction steps. Redact private hostnames, IPs, usernames, paths and all credentials before sharing diagnostics.

A shell works but files do not

Test SFTP separately. Shell login and SFTP availability are different questions, and a successful listing still does not prove a directory is writable. Ask the administrator about SFTP policy, path restrictions and ownership rather than changing all permissions.

Check the Docklark feature page for transfer validation notes. A source-implemented feature and a workflow verified against your actual server are different kinds of evidence.

Frequently asked questions