Troubleshooting

Known limitations

• RSA keys against a server that accepts only SHA-256 signatures. macSCP signs and verifies RSA keys with the SHA-512 variant; a server restricted to the SHA-256 one still refuses them, whether the key comes from a file or an agent.
• Several identities in your agent. They are offered as separate login attempts (at most six per connection). On a server running fail2ban with its default maxretry = 5, a single connect attempt can therefore trip the jail and get your address banned.
• Where the audit log lives. Per-session audit logs are stored in ~/Library/Application Support/macSCP/audit/, one file per saved connection. Deleting a saved connection deletes its log.
• No FTP or SMB/AFP support yet. SFTP, S3-compatible storage, and WebDAV are the three protocols macSCP speaks today.
• Cyberduck import does not yet cover WebDAV bookmarks. SFTP and S3-compatible bookmarks import; WebDAV ones are not recognised.
• The network route trace covers IPv4 only. An IPv6 route is not traced.
• Port forwarding needs a session with its own login. A session that uses a login set or a jump host cannot carry a forwarding.
• The CLI’s file commands do not go through a jump host. ls, get, put, rm and mkdir refuse such a session with exit code 10; diagnose goes through it.

A connection fails

Run the connection diagnostics — from the tab’s toolbar, the session’s context menu, or the failed connection’s error message. They tell you whether the name resolved, whether the host was reachable, whether the route got through, and where exactly the attempt broke. Copy the report as plain text or Markdown if you need to ask about it.

A connection is lost

A tab whose server stops answering shows Connection lost. The view now adds one sentence about the cause — the checks got no answer in time, the connection was closed by the server or by the network, or the last check ended in an error — and the diagnostic log records the same for every failed check, the moment the tab is given up on, and when each of a session’s connections closed, including whether macSCP closed it itself. Turn the log on in Settings → General → Diagnostic log before reproducing the drop, then read it as described under Reporting a bug.

A PEM key cannot be read

The failed connection names what stops it — an encryption, a password scheme or a key type macSCP does not read, or a PuTTY file. Press Convert key… to let macSCP convert a copy, or Copy command for the ssh-keygen -p command that converts the original file in place. See PEM private keys.

”managed_keys.json could not be read”

macSCP could not read its list of managed keys, so it could not look up a key’s saved passphrase. Every message about it names the file it could not read: ~/Library/Application Support/macSCP/managed_keys.json. Enter the passphrase by hand to connect, and check that file.

For a jump host’s key there is no field to type into while connecting, and the connection falls back to whatever is saved for the jump host itself. Check connection names the cause on the jump host’s rows, and names the same file there.

The server did not start SFTP

The SSH login worked, but the server offers no SFTP — common on jump boxes and locked-down hosts. The attempt ends when the wait for the file session times out — see How long a connect waits — and Details… says “This server did not start SFTP. It may not offer SFTP at all.” Port forwarding does not need SFTP and still works on such a server; the CLI exits with code 14.

The S3 endpoint is refused

“Enter the endpoint as a server address…” means the endpoint has an @ after the server name. Enter only the server address, such as https://s3.example.com, and put the access key and secret key in their own fields. See Credentials in a server address.

A port forwarding fails

The tunnels sheet’s State column names the cause — for example “Port 8080 is already in use” — and the Dock menu and the sidebar symbol show the same text as a tooltip. Active · N connections failed means the forwarding is up, but connections through it fail at the target; hover for the Last failure. See State and failures.

“The forwarding list could not be read, so it was not changed” means tunnels.json is damaged or was written by a newer version. macSCP leaves the file alone; check or restore it.

The throughput test left a file behind

If the throughput test could not delete its test file, the row says so and the details name it — a hidden file starting with .macscp-throughput- in the session’s start folder. The next throughput test tries to remove it again; if the server refuses, delete it by hand.

The host key changed

This is a hard stop by design — a changed host key is exactly what a man-in-the-middle attack looks like. Verify the key out of band (the server’s console, your hoster’s status page), then update it in Sessions → Known Hosts (⌘⇧K). The CLI reports it as exit code 12.

A transfer stalls

Open the transfer row: its tooltip or right-click menu shows the full source and destination path (a setting shows them permanently in every row). Cancel the row or the whole queue and reconnect — the queue keeps the remaining transfers after a connection loss and resumes when the tab reconnects.

An S3 download whose row reads “S3 did not answer with the byte range asked for, so the download was not resumed” came from a server that sent the whole file, or the wrong part, when macSCP asked for the rest. The partial file is left as it was; start the download again from the beginning. The quoted wording is the English one, and it is the whole message — not a technical note appended to one.

A failed transfer reads differently than it used to

Most failed transfers now show one sentence in the language macSCP is running in, with no English line after it. In v1.5.0 the same failures showed a general sentence followed by an English phrase marked as a technical detail. Nothing about the failure changed — only how it is written.

• The ending marked as a technical detail still appears for the failures that have no message of their own yet. When it does, quote it as it stands — it is in English.
• Where a message has changed wording, the meaning is the same one. A handful of near-identical sentences were merged into one, and two of them no longer end in text that came from elsewhere.
• The message above a folder listing that could not be opened is now a single sentence too, with no category in front of it.
• macscp-cli still prints its errors in English. For a named failure it now prints one fixed sentence, the same one the diagnostic log records, so a line copied from the terminal and a line found in the log match.

”could not be read” — an answer macSCP cannot use

Coming in the next release. v1.6.0 shows the second message for both cases.

Two messages say an answer could not be read, and they name different things.

• “The information the server sent about this item could not be read” — macSCP asked about one single file or folder, and the answer about it was damaged. Up to and including v1.6.0 this read as though the folder listing had failed, which pointed you at the wrong thing. The item is still there; only the answer describing it was unusable.
• “The folder listing the server sent could not be read” — the same kind of damaged answer, but for the contents of a folder. On S3-compatible storage it can also appear while deleting or renaming a folder, because both read the listing first.

Either way it is the server’s answer that is at fault, not the file. Both sentences are the whole message, in the language macSCP is running in, with nothing appended.

macscp-cli prints the same two sentences in English. It no longer appends the raw text the server or the system produced, so if you need that for a report, switch the diagnostic log on and capture it there — see Reporting a bug.

A rename or move is refused

Coming in the next release. v1.6.0 names the destination instead.

“The server refused the move because a condition on the request was not met” appears when a rename or move on a WebDAV server is turned down. Up to and including v1.6.0 the same refusal read “The destination already exists”, which pointed you at the wrong place: the server does not say which of its conditions failed, and the new name is often perfectly free.

What to check, in this order:

• Whether something really is already at the new name. That is the common cause, and the one you can fix yourself — pick a different name, or remove what is there.
• Whether the item is open or held somewhere else. Some servers refuse to move a file another program is still working on.
• Whether it keeps happening for the same file while other renames on the same server succeed. Servers can also attach conditions of their own that macSCP never asked for, and those are worth reporting — switch the diagnostic log on, repeat the rename, and send the entry as described under Reporting a bug.

macscp-cli prints the same sentence in English, with nothing appended.

The CLI cannot find ~/.local/bin

macscp-cli is only on your PATH if that folder is in it. See Installing the shortcut — and use Settings → Command Line → Repair if the shortcut points at an old app copy.

Reporting a bug

Turn on the diagnostic log in Settings → General, reproduce the problem, quit cleanly (so the log is flushed), and send the log with your report on the issue tracker. Include the connection diagnostics report — copy it as text from the panel.