Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Paramiko fails now and then with Error reading SSH protocol banner

Errorparamiko.ssh_exception.SSHException: Error reading SSH protocol banner

Short answer

Paramiko opens the TCP connection, then waits a short time for the server to send its SSH banner. If the banner is late or never sent, you get SSHException. Two documented causes: the wait (banner_timeout) is too short for a slow server, or sshd is dropping new connections because of its MaxStartups limit.

  • Applies to Paramiko 3.x, Python 3.13, OpenSSH 9.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Connect once from a plain terminal to the same host and port. If this is slow or fails too, the problem is on the server side, not in your Python code.

    ssh -v user@example.com
  2. 2Match what you see, then jump to its fix

    1. 1The error appears on a busy or distant host, and a retry a moment later worksbanner_timeout is shorter than the server needs to answerFix
    2. 2It happens when many threads or jobs connect to one host at the same momentsshd is dropping new connections (MaxStartups)Fix

What does the error look like?

  • paramiko.ssh_exception.SSHException: Error reading SSH protocol banner

Cause 1 of 2

banner_timeout is shorter than the server needs to answer

1Check

SSHClient.connect has a separate timeout for each stage: timeout is for the TCP connect, banner_timeout is how long to wait for the SSH banner, auth_timeout is for authentication. Look at which ones your call sets.

grep -n "banner_timeout\|\.connect(" your_script.py

2Fix

Pass a larger banner_timeout (in seconds) to connect().

import paramiko

client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.RejectPolicy())
client.load_system_host_keys()
client.connect(
    "example.com",
    username="deploy",
    key_filename="/home/deploy/.ssh/id_ed25519",
    timeout=15,
    banner_timeout=60,
)

3Verify

Run the script several times in a row. The error should stop appearing even when the host is slow to answer.

for i in 1 2 3 4 5; do python connect_test.py && echo ok; done

Confirmed by docs.paramiko.org

Did this fix it?

Cause 2 of 2

sshd is dropping new connections (MaxStartups)

1Check

sshd limits unauthenticated connections with MaxStartups (default 10:30:100). Above the limit it refuses a share of new connections, and from the client side that can look like a banner that never came. Read the value in use.

sudo sshd -T | grep -i maxstartups

2Fix

Open fewer connections at once (a pool of 5 to 8 workers, or one connection reused for many commands). If you run the server, raise MaxStartups in /etc/ssh/sshd_config and reload it.

# /etc/ssh/sshd_config
MaxStartups 30:30:100

# then
sudo sshd -t && sudo systemctl reload ssh

3Verify

Repeat the parallel run and confirm no connection fails.

python parallel_test.py

Confirmed by man.openbsd.org

Did this fix it?

How do I stop it coming back?

  • Set timeout, banner_timeout and auth_timeout explicitly instead of relying on defaults.
  • Cap how many SSH connections your code opens at once, and reuse one connection for several commands.
  • Retry a failed connect with a short back-off instead of failing the whole job.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.