Paramiko fails now and then with Error reading SSH protocol banner
paramiko.ssh_exception.SSHException: Error reading SSH protocol bannerShort 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.
Fix it fast
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.com2Match what you see, then jump to its 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.py2Fix
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; doneConfirmed by docs.paramiko.org
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 maxstartups2Fix
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 ssh3Verify
Repeat the parallel run and confirm no connection fails.
python parallel_test.pyConfirmed by man.openbsd.org
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Security
Paramiko key login fails after agreeing on rsa-sha2-512
paramiko.ssh_exception.AuthenticationException: Authentication failed.
Since Paramiko 2.9 an RSA key is signed with rsa-sha2-512 or rsa-sha2-256 instead of SHA-1.
2 causes, each with a fixSecurity
PyJWT decode fails with ValueError: Could not deserialize key data
jwt.exceptions.InvalidKeyError
jwt.decode hands your key to the cryptography library, which must read it as PEM or SSH.
3 causes, each with a fixSecurity
PyJWT will not decode a Keycloak or RS256 token: algorithm errors
jwt.exceptions.MissingCryptographyError
RS256 and ES256 need the cryptography package, and jwt.decode only accepts the algorithms you list.
4 causes, each with a fixSecurity
Python rejects a self-signed certificate in the chain
certificate verify failed: self signed certificate in certificate chain (_ssl.c:992)
Python could not build a trusted path from the server certificate to a root it knows.
3 causes, each with a fixSecurity
Entra ID token request fails: the request body must contain the parameter 'grant_type'
AADSTS900144: The request body must contain the following parameter: 'grant_type'.
The token endpoint did not find grant_type in the form body of your POST.
3 causes, each with a fixSecurity
Angular HttpClient does not add the X-XSRF-TOKEN header to a request
403 Forbidden on POST, PUT or DELETE while GET works
Angular copies the XSRF-TOKEN cookie into an X-XSRF-TOKEN header only for mutating requests to the same origin, and only when the cookie is readable by script.
5 causes, each with a fix