Azupay website
Guides
Help CentreService DeskStatus PageDashboard | ProductionDashboard | UATTest Bank
Start typing to search…

SFTP Connectivity Troubleshooting

Diagnose and resolve common SFTP connectivity issues with exact error messages, initial diagnostics, and step-by-step resolutions for both connectivity models.

1. SFTP Connectivity Troubleshooting

1.1 Purpose

This document lists common SFTP connectivity issues you may encounter when integrating Batch with Azupay and how to resolve them. It applies to both Azupay Hosted SFTP Server and Customer Hosted SFTP Server models. Follow the initial diagnostics, then use the exact error strings below to identify and fix the issue.

1.2 Initial diagnostics

  1. Collect verbose logs to see exactly what key and algorithms are used. 
    sftp -vvv -i ~/.ssh/KEY -P PORT USERNAME@HOST_NAME
# or
ssh  -vvv -i ~/.ssh/KEY -p PORT USERNAME@HOST_NAME
  2. Force the intended key if you have many keys loaded in your SSH agent. 
    sftp -o IdentitiesOnly=yes -o IdentityFile=~/.ssh/KEY -P PORT USERNAME@HOST_NAME
  3. Test basic reachability (DNS, route, firewall, port). 
    nc -vz HOST_NAME PORT
  4. Verify the server host key fingerprint before trusting/accepting it.
    • For Azupay Hosted SFTP Server: ask the Azupay Support Team to confirm the fingerprint for HOST_NAME.
    • For your Customer Hosted SFTP Server: compare with your own authoritative record, for example: 
      ssh-keyscan -p PORT HOST_NAME | ssh-keygen -lf -

1.3 Common errors and resolutions

1.3.1 Permission denied (publickey) or Permission denied (keyboard-interactive,publickey)

  1. Ensure the correct public key is installed for the correct user on the SFTP Server (authorized_keys).
  2. Fix permissions: the client private key must be 600 and ~/.ssh must be 700; authorized_keys should be 600 and its directory 700. 
    chmod 700 ~/.ssh && chmod 600 ~/.ssh/KEY
# on Customer Hosted server for the target USERNAME
chmod 700 ~USERNAME/.ssh && chmod 600 ~USERNAME/.ssh/authorized_keys
  3. Force the specific key and disable trying others: 
    sftp -o IdentitiesOnly=yes -o IdentityFile=~/.ssh/KEY -P PORT USERNAME@HOST_NAME
  4. Confirm Username (USERNAME), Host Name (HOST_NAME), and Port (PORT) match what you configured/received.

1.3.2 Server refused our key

  1. The public key on the server does not match the private key you are using, or it is in the wrong place.
  2. Re-install the exact public key from your private key: 
    ssh-keygen -y -f ~/.ssh/KEY > /tmp/key.pub
# compare /tmp/key.pub with the server's authorized_keys entry for USERNAME
  3. Check file ownership (must belong to USERNAME) and that no extra options in authorized_keys restrict login.

1.3.3 Load key '...': invalid format or unsupported key type

  1. Ensure you are using a private key file.
  2. If you copy/pasted the key, recopy without line wrapping or Windows CRLF conversions.
  3. Regenerate an ed25519 (preferred) or RSA‑4096 key if needed: 
    ssh-keygen -t ed25519 -f ~/.ssh/KEY -C USERNAME@your-org

1.3.4 Bad permissions or Unprotected private key file

  1. Tighten permissions on the key and directory as SSH will refuse loose permissions. 
    chmod 700 ~/.ssh
chmod 600 ~/.ssh/KEY

1.3.5 Host key verification failed or REMOTE HOST IDENTIFICATION HAS CHANGED!

  1. Do not proceed until you verify the server fingerprint out‑of‑band.
  2. If the change is expected (e.g., planned rotation), update known_hosts: 
    ssh-keygen -R HOST_NAME
ssh-keyscan -p PORT HOST_NAME >> ~/.ssh/known_hosts
  3. For Azupay Hosted SFTP Server, confirm the new fingerprint with the Azupay Support Team before updating known_hosts.

1.3.6 Connection timed out

  1. Firewall/route is blocking or the server is not reachable on PORT.
  2. Common when using the wrong port if the firewall drops packets to closed ports (though behavior varies by firewall configuration; some may return "Connection refused" instead).
  3. For Customer Hosted SFTP Server, ensure you have allow‑listed Azupay outbound IPs (see Connectivity Guide 1.3.2.3 Requirements: ./connectivity-guide.md#1323-requirements) and that your SFTP Server is internet‑reachable.
  4. For Azupay Hosted SFTP Server, ensure your corporate egress allows TCP 22 to HOST_NAME.
  5. Validate reachability: 
    nc -vz HOST_NAME PORT

1.3.7 Connection refused

  1. SSH service not running/listening on the specified PORT, or using the wrong port number.
  2. This error indicates the port is reachable but no service is listening. May occur when using wrong ports depending on firewall configuration (some firewalls return this instead of timeout).
  3. Confirm the Port (PORT) and that sshd is listening; adjust the Dashboard/received settings accordingly.

1.3.8 No route to host or Network is unreachable

  1. DNS, routing, or upstream firewall issue. Verify HOST_NAME resolves and routes exist.
  2. Try the alternate hostname for the environment (see Connectivity Guide 1.3.1.1 Environments and endpoints: ./connectivity-guide.md#1311-environments-and-endpoints) or test from another network segment.

1.3.9 no matching host key type found / no matching key exchange method found / no matching cipher found

  1. Your client/server algorithm sets are incompatible. Prefer upgrading the older side to support modern algorithms (ed25519, ecdsa‑sha2‑nistp256, curve25519‑sha256).
  2. As a temporary workaround (not preferred), you can specify algorithms explicitly: 
    sftp -o HostKeyAlgorithms=ssh-ed25519,ecdsa-sha2-nistp256 -o KexAlgorithms=curve25519-sha256 -P PORT USERNAME@HOST_NAME

1.3.10 Received disconnect: Too many authentication failures or too many authentication failures

  1. Your SSH agent is offering many keys; the server disconnects before your intended key is tried.
  2. Force only the intended key: 
    sftp -o IdentitiesOnly=yes -o IdentityFile=~/.ssh/KEY -P PORT USERNAME@HOST_NAME
  3. Alternatively, unload extra keys from your agent (ssh-add -D) and add only the required one (ssh-add ~/.ssh/KEY).

1.3.11 kex_exchange_identification: read: Connection reset by peer or Connection closed by remote host

  1. Often caused by security blocks (e.g., fail2ban), IP not allow‑listed, or rate limiting.
  2. For Customer Hosted SFTP Server, ensure your controls allow Azupay’s IPs and that your server is not actively banning the source.
  3. Retry after removing the block or adding the allow‑list entry.

1.3.12 subsystem request failed on channel 0 (SFTP)

  1. SFTP subsystem disabled/misconfigured on the server. For Customer Hosted SFTP Server, enable the SFTP subsystem in sshd_config and reload sshd.
  2. On Azupay Hosted SFTP Server this should not occur; contact Support if seen.

1.3.13 Upload path issues (file appears to connect but upload fails or nothing is processed)

  1. Verify you are writing to the correct Upload Folder (UPLOAD_FOLDER) for Azupay Hosted or Folder (FOLDER) for Customer Hosted, as configured.
  2. Confirm case sensitivity and that the user has read/write permissions to the path.
  3. Re-test with a small file and watch the server logs (Customer Hosted) while uploading.

1.4 When to contact Support

If the issue persists, capture the following and send to [email protected]:

  • Full verbose output (-vvv) of the failing connection attempt.
  • Timestamp, environment (UAT/Production), connectivity model (Azupay Hosted SFTP Server or Customer Hosted SFTP Server).
  • Username (USERNAME), Host Name (HOST_NAME), Port (PORT).
  • Your source IP address.

Updated 2 months ago