Connection diagnostics

When a connection misbehaves, the connection diagnostics measure the path to the server step by step and report where it breaks.

Where to open it

Choose Diagnose…:

from an open tab’s toolbar,
from a saved session’s context menu or its overview,
straight from a failed connection’s error message.

The steps

Step	What it measures
Name lookup	Resolves the host name. Also names each address it found and checks the name back — see Address names.
Reachability	Asks the network whether the host is reachable at all.
Ping	Sends an ICMP echo — without needing administrator rights.
Connect	The connection attempt itself.
Route trace	Follows the IPv4 route hop by hop, on unprivileged sockets.
Protocol-specific	S3 and WebDAV get their own checks — for example the server’s claims and an S3 key’s access level, as contributions to the report.
Throughput	Uploads and downloads a test file — only when you choose it; see The throughput test.
Internet speed	Measures this Mac’s own internet line, not your server — only when you choose it; see The internet speed test.

Run everything at once or just one step. Rows appear as steps finish, and the running line names the step in flight; the route trace renders as a table.

What a row says

Each row ends with one word, and the word says who the row is about:

Row reads	Means
OK	The step did what it set out to do.
Failed	The server, or the path to it, gave an answer that is a finding. The details say what.
Timed out	The step ran and did not finish inside its time.
Not available	This build cannot run the step.
Skipped	There was nothing to run — an earlier step left this one with no host, no address or no connection.
Not started	This Mac was too busy to start the step at all.

Only the first three say anything about your server. The last three are about your own side, and they are kept apart on purpose: a row that measured nothing must never read as a server that is broken.

”Not started”

This one is about your Mac, not about the server. Each step is given a time to answer in, and that time starts when the step is set up. If the machine is busy enough — a long build, an export, a big import, a batch of your own work — the step can still be waiting its turn when its time is up. Nothing was sent anywhere, so the row says so instead of blaming the far end.

Before this, such a row read Timed out, which is a sentence about the server. A report pasted into a bug report could accuse a server the app had never contacted.

What to do: run the diagnosis again when the Mac has less to do. If the rows come back normally, there was nothing wrong with the connection. On the command line the same row reads notStarted, and it does not set a failure exit code.

Address names

The name lookup shows a table with one line per address it found:

Column	Shows
Address	The IPv4 or IPv6 address.
Name	The name the address’s reverse lookup gives, or ”—”.
Check	Resolves back — the name leads back to this address. Does not resolve back — it does not. No name — the address has no reverse name. No answer — the lookup did not answer. An address, not a name — the reverse name is itself an address.

The table is information only: it never changes whether the step counts as passed. A name that does not resolve back is reported, not judged.

Sessions behind a jump host

A session that connects through a jump host is diagnosed through that jump host. The panel shows “through the jump host …” under the target, and the steps check the jump host first, then reach the target from there:

Step	Runs
Jump host: name resolution	on this Mac
Jump host: connection attempt	on this Mac
Jump host: ping	on this Mac
Jump host: SSH connect	on this Mac — logs in to the jump host
Jump host: route	on this Mac
Target via the jump host: connection attempt	through the jump host
Target via the jump host: name resolution	on the jump host
Target via the jump host: ping	on the jump host
Target via the jump host: SSH connect	on this Mac, through the jump host — the same way a tab connects
Target via the jump host: route	on the jump host

Before you press Run, the panel describes the check it is about to make — and for a session with a jump host it describes this one: the jump host first, then the target through it.

The steps that run on the jump host use its own tools — getent, ping, and traceroute or tracepath. When the jump host lacks one, or allows forwarding but no commands, the row says so, for example “The jump host has no ping.” When the jump host is not reached, every target step reads “Not measured: the jump host was not reached.”

A jump host that allows forwarding and nothing else refuses the command outright, and the row now names which one it refused — “the jump host refused to run ping and gave no reason of its own” — instead of the technical message the connection library produced, which named neither the tool nor the reason.

The jump host’s saved login is used only to log in to the jump host, and the target’s only for the target. When no login is saved for the jump host, the steps that need one say so: “No credential is saved for the jump host.”

When the jump host logs in with a key held by the key manager and that key’s saved passphrase could not be looked up — because the list of managed keys could not be read — those steps say that instead: “The jump host’s key passphrase could not be looked up…”. Nothing is saved for you to find in that case, so the two are worth telling apart: the first asks you to save a credential, the second to check the file.

The throughput test

Throughput is a separate choice in the list of what to run. Everything does not include it, because it writes to your server.

It connects the way the session does — over SFTP, S3 or WebDAV, and through the jump host if there is one — and then:

removes test files an earlier run left behind,
uploads a hidden test file (.macscp-throughput-…) to the session’s start folder,
downloads it and compares it with what was sent,
deletes it — also after a failure or a cancel.

The result is a table with Direction (Upload, Download), Bytes, Time, Rate and Limit. The test passes when the file came back identical and was removed; the speed never decides that.

The file’s size is set under Settings → Transfers → Test file size — 1 to 256 MiB, 8 MiB by default.
The bandwidth limits under Settings → Transfers apply, and the Limit column shows them.
An S3 session that starts at the bucket list has no folder to write to, so the test is not available there.
If the file could not be deleted, the row says “The test file may have been left on the server — its name is in the details.” The next throughput test tries to remove it again; if that fails too, delete it by hand.

The internet speed test

Internet speed is a separate choice in the list of what to run, and it is the only one that measures nothing about your server. It measures the line between this Mac and a speed test service, so it is useful when you want to know whether a slow transfer is your connection or the server.

Everything does not include it, because it contacts a company that is not you and not your server.

It downloads 10 MiB from the chosen service and then uploads 1 MiB to it, and reports a rate for each direction:

Column	Shows
Direction	Download, Upload.
Bytes	How many bytes crossed.
Time	How long that direction took.
Rate	Bytes over time. Reported, never judged.

What is sent. Generated data and nothing else. No server name, no user name, no password, no folder, no cookie, and not your language either — nothing about the connection the panel was opened from, and nothing about you, travels to the service, and the report does not name your server. The row itself says which service was used and what each request was, so you can check it.

Choosing the service. Settings → Transfers → Internet speed test → Speed test service:

Choice	Measures against
Cloudflare (default)	`speed.cloudflare.com`.
Apple	`mensura.cdn-apple.com`, the same endpoint macOS uses for its own network quality measurement.
Off	Nobody. The step still runs and its row says the test is switched off — nothing is sent.

The list is fixed: there is no field to type an address into, so nothing an imported file or a web page hands you can decide where this app sends a request.

When it does not finish. Each direction is given 45 seconds. A service that refuses, or a line too slow to finish a direction in that time, reads not available with the reason — never failed, because a busy speed test service is not a finding about your server. A direction this Mac was too busy to start reads not started instead, for the reason above: nothing was sent, so the service is not what the row is about. The test stops at the first direction that did not finish, so a broken line costs one wait, not two.

If the service tries to send the request somewhere else. A speed test service that answers with a redirect to another server is refused, and nothing — including the uploaded data — is sent there. The row reads not available and the details name both addresses. A redirect that stays on the service’s own address is followed as usual.

The report

A diagnosis ends with its sheet or its tab, and a cancelled report says it was cancelled. Copy the report as plain text or Markdown. A report names no credentials: no password, no key, no session secret reaches the text. A changed host key is reported as “host key MISMATCH for …: the presented key differs from the recorded one” — the host’s name, without the fingerprints — in the report and in the diagnostic log.

The diagnostic log

For bug reports, macSCP can write a diagnostic log: choose the level in Settings → General, and the app writes it off the caller’s path — listings, connects, SFTP requests and transfers included. The settings show the folder and a way to find it.