Python

TimeoutError: What It Means and How to Fix It

Error reference

TimeoutError

Language

Python

Severity

Medium

When it happens

TimeoutError is raised when a socket or I/O operation exceeds the time limit set by a timeout.

Potential fixes

Always set explicit timeouts on network operations rather than waiting indefinitely. Implement retry logic with exponential backoff for transient timeouts. Distinguish between connection timeouts (server unreachable) and read timeouts (server connected but slow to respond).

Deep dive

TimeoutError is raised when a socket or I/O operation exceeds the time limit set by a timeout. It is a subclass of OSError. Many third-party libraries (requests, httpx, asyncio) wrap this as their own timeout exception.

Why it happens

•A socket.settimeout() value is exceeded before a connection or read completes.
•A remote server is overloaded and doesn't respond within the allowed time.
•Network congestion or packet loss causes the operation to stall.
•The asyncio.wait_for() timeout fires before the coroutine finishes.

Potential fixes

Always set explicit timeouts on network operations rather than waiting indefinitely. Implement retry logic with exponential backoff for transient timeouts. Distinguish between connection timeouts (server unreachable) and read timeouts (server connected but slow to respond).

Examples

Python

Code that triggers the error

import socket

s = socket.socket()
s.settimeout(2)
s.connect(("10.255.255.1", 80))  # unreachable host

Error output

TimeoutError: timed out

Fixed code

import socket

s = socket.socket()
s.settimeout(5)
try:
    s.connect(("10.255.255.1", 80))
except TimeoutError:
    print("Connection timed out, host unreachable")
finally:
    s.close()

Practice in English

How would you explain a TimeoutError to a fellow dev? Choose the right phrase:

"I hit an error...

Ready to practice your English at work?

Lingua-e has interactive exercises built around real developer conversations: standups, code reviews, retrospectives, and more. Practice until it comes naturally.

Try Lingua-e for free