GCS errors

Network connection errors

Dial tcp - i/o timeout

$ connect test sftp -h 10.0.0.24 -l monitor02 -p pass
2024/12/20 14:34:41 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 14:34:41 INFO Licensed for: Ultimate
2024/12/20 14:34:41 INFO Testing connection to sftp://[email protected]
2024/12/20 14:34:41 ERROR Error while testing connection: dial tcp 10.0.0.24:22: i/o timeout

SFTP client was unable to establish a TCP connection to the target server within the allowed timeout period.

Possible causes:

• target server is down
• network issues (different subnets, no route, or disconnected network)
• a firewall (on the client, target, or intermediate network) is blocking connections
• SSH service on the target server is not running or running on different port
• timeout to short

Dial tcp - connection refused

$ connect test sftp -h 10.0.0.24 -l monitor02 -p pass
2024/12/31 09:15:26 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 09:15:26 INFO Licensed for: Ultimate
2024/12/31 09:15:26 INFO Testing connection to sftp://[email protected]:22
2024/12/31 09:15:26 ERROR Error while testing connection: dial tcp 10.0.0.24:22: connect: connection refused

SFTP client was unable to establish a TCP connection to the target server as connection was actively refused by the target machine.

Possible causes:

• the target machine is not running a SSH server or the service is not configured to listen specified port
• firewall is blocking the target port

Dial tcp - no route to host

$ connect test sftp -h 10.0.0.25 -l monitor02 -p pass
2024/12/20 14:30:28 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 14:30:28 INFO Licensed for: Ultimate
2024/12/20 14:30:28 INFO Testing connection to sftp://[email protected]
2024/12/20 14:30:28 ERROR Error while testing connection: dial tcp 10.0.0.25:22: connect: no route to host

SFTP client attempting to connect to the IP address cannot find a network route to the destination. This typically indicates a network-related issue preventing connectivity between the client and the target machine.

Possible causes:

• target machine might be powered off or disconnected from the network
• target IP might not be assigned to any device, or there may be misconfigurations (e.g., subnet mask or gateway settings)
• the client and target machine might be on different subnets, and there’s no route or gateway configured to connect them
• a firewall (on the client, target, or an intermediate device) is blocking the connection or the network path
• the network interface on the target machine might be down or misconfigured
• the client’s network configuration may prevent it from accessing the target (e.g., wrong subnet, missing gateway)
• loose or disconnected cables, failed switches, or network hardware issues

Dial tcp - network is unreachable

$ connect test sftp -h 10.0.0.25 -l monitor02 -p pass
2024/12/20 14:30:28 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 14:30:28 INFO Licensed for: Ultimate
2024/12/20 14:30:28 INFO Testing connection to sftp://[email protected]
2024/12/20 14:30:28 ERROR Error while testing connection: dial tcp 10.0.0.25:22: connect: network is unreachable

SFTP client cannot even attempt to connect to the target IP address because there is no valid network route to reach it. This is a local network issue, meaning the client is unable to determine how to communicate with the target IP.

Possible causes:

• the client is not connected to any network (e.g., Wi-Fi is disabled, Ethernet cable is unplugged)
• the client is misconfigured with an incorrect subnet, IP address, or no default gateway.
• the target IP is not in the same subnet as the client, and no router or gateway exists to handle communication between the two
• the client’s routing table does not include a route for the target network
• the client’s network interface (e.g., eth0 or wlan0) is disabled or not operational
• a local firewall or security application is blocking the network traffic

Failed to transfer file - connection lost

$ connect send sftp -h 10.0.0.24 -l monitor02 -p pass --file test-file.txt --batch
2024/12/31 13:26:52 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 13:26:52 INFO Licensed for: Ultimate
2024/12/31 13:26:52 INFO Sending files to sftp://[email protected]:
2024/12/31 13:26:54 INFO Transferring file=test-file.txt sftpSessionID=1 targetFolder=
2024/12/31 13:27:02 ERROR Failed to transfer file error=connection lost file=test-file.txt sftpSessionID=1 targetFolder=
2024/12/31 13:27:02 ERROR Error while closing dst file error=connection lost file=test-file.txt sftpSessionID=1

This error occurs when an SFTP session unexpectedly disconnects during file transfer.

Possible causes:

• intermittent or unstable network connection between the client and the server
• high latency, packet loss, or insufficient bandwidth
• firewall or NAT timeout closing the connection prematurely
• SSH/SFTP server crashes or becomes unresponsive during the transfer
• resource limitations on the server (e.g., CPU, memory, or disk space exhaustion)
• server timeouts or limits (e.g., session timeouts, file size limits, etc.)
• resource limitations on the client device (e.g., running out of memory or CPU)
• transferring large files over unstable connections can result in interruptions
• some firewalls or intrusion detection/prevention systems might incorrectly terminate an SFTP session, seeing it as “idle” or suspicious

Failed to transfer file - timeout mid transmission (TODO)

DNS errors

Dial tcp - no such host

$ connect test sftp -h example.com -l monitor01 -p pass
2024/12/20 19:38:44 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 19:38:44 INFO Licensed for: Ultimate
2024/12/20 19:38:44 INFO Testing connection to sftp://[email protected]
2024/12/20 19:38:44 ERROR Error while testing connection: dial tcp: lookup example.com on 127.0.0.53:53: no such host

SFTP client attempted to resolve the hostname using the DNS server at 127.0.0.53 (typically a local DNS resolver), but the hostname could not be found. This indicates a DNS resolution failure.

Possible causes:

• the hostname does not exist, either due to a typo or because it hasn’t been configured in DNS
• the local DNS resolver cannot forward the query to upstream DNS servers or is misconfigured
• the client is unable to reach the upstream DNS servers due to network problems
• the upstream DNS server cannot resolve the query
• outgoing DNS requests are blocked, preventing the client from contacting DNS servers
• the hostname may have recently been removed or changed, and the DNS cache contains outdated information

Dial tcp - lookup i/o timeout

connect test sftp -h example.com -l monitor01 -p pass
2024/12/20 19:43:57 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 19:43:57 INFO Licensed for: Ultimate
2024/12/20 19:43:57 INFO Testing connection to sftp://[email protected]
2024/12/20 19:43:57 ERROR Error while testing connection: dial tcp: lookup example.com on 127.0.0.53:53: read udp 10.0.0.51:40270->127.0.0.53:53: i/o timeout

SFTP client attempted to resolve the domain, but the DNS query timed out. This means the DNS server did not respond within the expected time frame.

Possible causes:

• the local DNS resolver is not functioning correctly or is misconfigured
• the local resolver cannot forward the query to an upstream DNS server (e.g., Google DNS, Cloudflare DNS)
• the system cannot reach the upstream DNS servers due to network issues
• a firewall is blocking DNS traffic
• the upstream DNS server is overloaded or temporarily unavailable
• the resolver might have stale or corrupted cached data causing delays

Authentication errors

Handshake failed - unable to authenticate, attempted methods [none password], no supported methods remain

$ connect test sftp -h 10.0.0.24 -l monitor02 -p pass
2024/12/31 10:42:16 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:42:16 INFO Licensed for: Ultimate
2024/12/31 10:42:16 INFO Testing connection to sftp://[email protected]
2024/12/31 10:42:18 ERROR Error while testing connection: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none password], no supported methods remain

SFTP client attempted to connect to the remote server but was unable to authenticate successfully with password based authentication.

Possible causes:

• the password provided for the SFTP user is incorrect
• the SFTP server is configured to disallow password-based authentication
• the client is attempting to authenticate with the wrong username
• the server requires a different authentication method that the client isn’t attempting (e.g., public key, GSSAPI)
• the user account on the SSH server may be locked, disabled, or misconfigured

Handshake failed - unable to authenticate, attempted methods [none publickey], no supported methods remain

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ed25519
2024/12/20 15:02:33 INFO License valid to: 2026-04-13 18:06:28
2024/12/20 15:02:33 INFO Licensed for: Ultimate
2024/12/20 15:02:33 INFO Testing connection to sftp://[email protected]
2024/12/20 15:02:33 ERROR Error while testing connection: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain

SFTP client attempted to connect to the remote server but was unable to authenticate successfully with key based authentication.

Possible causes:

• the client either doesn’t have an SSH key or isn’t using the correct private key
• thr server does not have the corresponding public key in the user’s authorized_keys file
• the client is attempting to authenticate with the wrong username
• the client is trying to authenticate with a username that doesn’t have a valid public key configured on the server
• the private key is not loaded into the SSH agent, so the client cannot use it
• the server is configured to allow only certain types of authentication (e.g. only password based auth)

Can’t read identity file - no such file or directory

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ecdsa
2024/12/31 08:54:52 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 08:54:52 INFO Licensed for: Ultimate
2024/12/31 08:54:52 ERROR Can't read identity file error=open .ssh/id_ecdsa: no such file or directory

SFTP client is trying to use a private key to authenticate with the server, but the private key file does not exist.

Possible causes:

• private key does not exists at specified location

Can’t read identity file - permission denied

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ecdsa
2024/12/31 08:57:55 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 08:57:55 INFO Licensed for: Ultimate
2024/12/31 08:57:55 ERROR Can't read identity file error=open .ssh/id_ecdsa: permission denied

SFTP client is trying to use a private key to authenticate with the server, but is unable to read the file due to wrong permissions.

Possible causes:

• permissions to the key file are incorrect

Failed to parse private key - this private key is passphrase protected

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ecdsa.pub
2024/12/31 08:47:51 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 08:47:51 INFO Licensed for: Ultimate
2024/12/31 08:47:51 INFO Testing connection to sftp://[email protected]
2024/12/31 08:47:51 ERROR Error while testing connection: failed to parse private key: ssh: no key found

SFTP client is trying to use a private key to authenticate with the server, but the private key is encrypted with a passphrase, and the client did not provide the passphrase. As a result, it cannot parse or use the key to authenticate.

Possible causes:

• no password provided and the private key is password protected (please add -k, --identity-passphrase or --identity-passphrase-file option)

Failed to parse private key - decryption password incorrect

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ecdsa -k pass
2024/12/31 09:04:25 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 09:04:25 INFO Licensed for: Ultimate
2024/12/31 09:04:25 INFO Testing connection to sftp://[email protected]
2024/12/31 09:04:25 ERROR Error while testing connection: failed to parse private key: x509: decryption password incorrect

SFTP client is trying to use a password-protected private key to establish the connection but it cannot decrypt the private key.

Possible causes:

• the password provided is incorrect, preventing the tool from decrypting the private key

Failed to parse private key - no key found

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ecdsa
2024/12/31 10:47:02 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:47:02 INFO Licensed for: Ultimate
2024/12/31 10:47:02 INFO Testing connection to sftp://[email protected]
2024/12/31 10:47:02 ERROR Error while testing connection: failed to parse private key: ssh: no key found

SFTP client is trying to use a private key to authenticate with the server but the private key is malformed.

Possible causes:

• private key is not in the correct format (e.g., missing headers, incomplete, or not actually a private key file)

Can’t read password file - no such file or directory

$ connect test sftp -h 10.0.0.24 -l monitor02 --password-file job1_pass
2024/12/31 10:48:30 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:48:30 INFO Licensed for: Ultimate
2024/12/31 10:48:30 ERROR Can't read password file error=open job1_pass: no such file or directory

SFTP client is trying to access a file which is supposed to contain a password, but the file does not exist in the specified location.

Possible causes:

• file with password does not exist in specified location

Can’t read password file - message authentication failed

$ connect test sftp -h 10.0.0.24 -l monitor02 --password-file job1_pass
2024/12/31 10:51:42 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:51:42 INFO Licensed for: Ultimate
2024/12/31 10:51:42 ERROR Can't read password file error=cipher: message authentication failed

SFTP client is trying to access a file which is supposed to contain encrypted password, but the file is malformed.

Possible causes:

• the file containing encrypted password is malformed

Can’t read passphrase file - no such file or directory

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ed25519 --identity-passphrase-file key1_pass2
2024/12/31 10:56:21 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:56:21 INFO Licensed for: Ultimate
2024/12/31 10:56:21 ERROR Can't read passphrase file error=open key1_pass2: no such file or directory

SFTP client is trying to access a file which is supposed to contain password for the key, but that file is missing.

Possible causes:

• file with password to key private key does not exist in specified location

Can’t read passphrase file - message authentication failed

$ connect test sftp -h 10.0.0.24 -l monitor01 -i .ssh/id_ed25519 --identity-passphrase-file key1_pass
2024/12/31 10:55:00 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 10:55:00 INFO Licensed for: Ultimate
2024/12/31 10:55:00 ERROR Can't read passphrase file error=cipher: message authentication failed

SFTP client is trying to access a file which is supposed to contain encrypted password for the private key, but the file is malformed.

Possible causes:

• the file containing encrypted password for key private key is malformed

Error while getting sftp session - key mismatch

$ connect send sftp -h 10.0.0.24 -l monitor02 -p pass -s /data --file-mask "*.zip" --batch -d target
2024/12/31 13:15:57 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 13:15:57 INFO Licensed for: Ultimate
2024/12/31 13:15:57 INFO Sending files to sftp://[email protected]:
2024/12/31 13:15:58 ERROR Error while getting sftp session error=ssh: handshake failed: knownhosts: key mismatch file=main.go

SFTP client tries to connect but the host key of the server does not match the key stored in known_hosts file. This is a security mechanism in SSH to prevent man-in-the-middle (MITM) attacks by ensuring you’re connecting to the correct server.

Possible causes:

• the server has updated its SSH host key (e.g., after a reinstallation or configuration change)
• the server’s hostname or IP address now points to a different server with a different SSH host key
• if someone is intercepting your connection and posing as the server, you’ll see this error because the host key doesn’t match.
• a previous connection to a different server with the same IP/hostname has left an old host key in your known_hosts file

Note

If you are sure the key is correct and want to overwrite it please rerun the command without --batch option. It will ask to update the host key.

$ connect send sftp -h 10.0.0.24 -l monitor02 -p pass -file-mask "*.zip" -d target
2024/12/31 13:22:40 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 13:22:40 INFO Licensed for: Ultimate
2024/12/31 13:22:40 INFO Sending files to sftp://[email protected]:
The key of 10.0.0.24:22 does not match the one in known_hosts. Do you want to update this key in known_hosts (y/n): y
2024/12/31 13:24:52 WARN No file to send

Permission errors

Error while reading folder - file does not exist

$ connect list sftp -h 10.0.0.24 -l monitor02 -i .ssh/id_ed25519 -d abc
2024/12/31 11:15:50 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 11:15:50 INFO Licensed for: Ultimate
2024/12/31 11:15:50 INFO Listing sftp://[email protected]:abc
2024/12/31 11:15:50 ERROR Error while reading folder: file does not exist

SFTP client is attempting to access or list a directory that doesn’t exist on the SFTP server.

Possible causes:

• directory doesn’t exist on the SFTP server

Error while reading folder - permission denied

$ connect list sftp -h 10.0.0.24 -l monitor02 -p pass -d abc
2024/12/31 11:27:44 INFO License valid to: 2026-04-13 18:06:28
2024/12/31 11:27:44 INFO Licensed for: Ultimate
2024/12/31 11:27:44 INFO Listing sftp://[email protected]:abc
2024/12/31 11:27:46 ERROR Error while reading folder: permission denied

SFTP client does not have sufficient permissions to access or read the contents of a specific directory on the server.

Possible causes:

• user account does not have the necessary read permissions for the folder (r-x)
• the folder is owned by a different user, and your account isn’t in the group that has access
• the directory permissions may be restrictive, or Access Control Lists (ACLs) are preventing access
• the SFTP server might be configured to limit your access to specific directories (e.g., a chroot jail)
• the folder might be a symbolic link or mount point pointing to a location your user cannot access

Failed to create destination file - file does not exist

connect send sftp -h 10.0.0.24 -l monitor02 -p pass -s /data --file-mask "*.zip" --batch -d target1
2024/12/30 10:05:42 INFO License valid to: 2026-04-13 18:06:28
2024/12/30 10:05:42 INFO Licensed for: Ultimate
2024/12/30 10:05:42 INFO Sending files to sftp://[email protected]:target1
2024/12/30 10:05:44 ERROR failed to create destination file error=file does not exist file=/data/file1.zip sftpSessionID=1
2024/12/30 10:05:44 INFO Disconnected sftpSessionID=1 target=sftp://[email protected]:

SFTP client tries to upload a file but the destination file cannot be created because the target directory does not exist.

Possible causes:

• target directory does not exist

Failed to create destination file - permission denied

$ connect send sftp -h 10.0.0.24 -l monitor02 -p pass -s /data --file-mask "*.zip" --batch -d target
2024/12/30 10:12:47 INFO License valid to: 2026-04-13 18:06:28
2024/12/30 10:12:47 INFO Licensed for: Ultimate
2024/12/30 10:12:47 INFO Sending files to sftp://[email protected]:target
2024/12/30 10:12:48 ERROR failed to create destination file error=permission denied file=/data/file1.zip sftpSessionID=1
2024/12/30 10:12:48 INFO Disconnected sftpSessionID=1 target=sftp://[email protected]:

SFTP client attempts to upload a file but does not have sufficient permissions to write to the target directory or create the destination file.

Possible causes:

• your user account does not have the necessary write permissions for the target directory
• the directory or file is owned by another user, and your account doesn’t belong to the group that has write access
• file already exists and your user lacks the permissions to overwrite it
• the target directory might be mounted as read-only
• the server may impose write restrictions on specific directories (e.g., a chroot jail)