You can fix curl error 28 connection timed out after x milliseconds by increasing your request timeout setting. This error occurs when a server takes longer to respond than your client allows, often due to network congestion or high server load. Adjusting this value gives your request the extra time needed to finish.
Why curl connections time out
A connection timeout occurs when your machine can’t establish a handshake with the remote server within the pre-set limit. The most common cause is a slow network path where data packets are dropped or delayed significantly. If you’re on a home or office network, a temporary spike in traffic can cause this latency.
Another frequent cause is server-side processing delay. If the remote service is performing a complex database query or generating a large report, it may not send a response header until the task is complete. In these cases, the default timeout—often as low as 30 seconds in many environments—is simply not enough. Finally, firewall rules or proxy servers may intercept your request and hold it in a queue, causing the client to wait indefinitely until the internal timer triggers the error. You can verify your current system network settings by checking the official curl documentation for details on how the timeout flag functions across different operating systems.
Increase the request timeout limit
If you’re using the command line, this fix is for users who know the server is functional but slow. You can override the default limit by adding the --max-time or -m flag to your command followed by the number of seconds you want to allow. For example, if you expect a slow response, setting -m 60 gives the request one full minute to finish.
This isn’t for users experiencing a total network outage; if you can’t reach a website in your browser, changing a timer won’t fix the underlying connection issue. When you run your command, watch the output to see if it succeeds after the extra wait. If it still fails, the server might be completely unresponsive rather than just slow. This assumes you have permission to modify the request parameters; if you’re using a locked-down enterprise tool, you may need to ask your network administrator to increase the global timeout policy for your specific user group.
Optimize your network connection path
This fix is for users who suspect their local internet connection is the bottleneck. If you’re on a restricted network, switching to a more stable connection, such as an ethernet cable instead of Wi-Fi, often reduces jitter and packet loss. Jitter is the variation in the time it takes for packets to arrive, which frequently triggers false timeouts in sensitive applications.
If you’re working from a remote location, try using a VPN to see if it routes your traffic through a more efficient path. If the error persists, the issue is likely with the ISP or the server host. This fix isn’t for those who have a stable connection but are trying to access a server that’s physically located on the other side of the world. Distance creates inherent latency that no software setting can fully overcome. If your ping times to the server are consistently high, you should look for a mirror server or a content delivery network closer to your physical location to improve performance.
Adjust the server response expectations
For complex tasks that take a long time, consider splitting the work into smaller, asynchronous requests. Instead of waiting for a single, massive response that times out, ask the server for a status update or a smaller chunk of data. This is worth the extra effort when you’re building automated scripts that must run reliably without manual intervention.
This isn’t for simple API calls that should return data in under a second. If a basic request is taking longer than 10 seconds, there’s likely a deeper configuration problem on the server side that simply waiting longer won’t solve. If you have access to the server, check the logs to see if the process is hanging or if there are insufficient resources like RAM or CPU available to handle your request. If you don’t manage the server, contact the API provider’s support team to report the latency; they may have a specific endpoint designed for long-running processes that you should be using instead.
Common mistakes to avoid
- Setting the timeout to an extremely high number like 3600 seconds, which leaves your application hanging for an hour if the server is actually down.
- Ignoring network latency by assuming the server is the only point of failure, which leads to wasted time troubleshooting the wrong end of the connection.
- Running multiple requests in parallel without adjusting local connection limits, which can lead to socket exhaustion on your machine.
- Hardcoding timeout values into production scripts without considering that different environments may have vastly different network speeds.
Prevent future connection errors
To keep your connections stable, compare your current setup with the standard practices for network communication.
| If you’re doing this | Do this instead | Why |
|---|---|---|
| Using default settings | Define explicit timeouts | Prevents indefinite hangs |
| Relying on Wi-Fi | Use a wired connection | Reduces packet loss/latency |
| Single long request | Use asynchronous polling | Avoids blocking the thread |
| Ignoring error logs | Log the specific error | Helps identify the bottleneck |
Frequently asked questions
Can I set the timeout to zero?
No, setting the timeout to zero typically tells the program to wait forever, which is the opposite of a fix. If the server hangs, your application will freeze and consume resources until you manually kill the process. Always use a finite, reasonable number of seconds that reflects the maximum time you’re willing to wait for a specific task to complete.
How long should the timeout be?
The ideal timeout is usually 5 to 10 seconds for standard web requests, but it varies based on the expected server response time. If you’re fetching large files or running complex reports, you may need 60 to 120 seconds. Test your request multiple times to find the average completion time, then set your limit to roughly double that value to account for normal network fluctuations.
Is it safe to ignore this error?
No, ignoring this error isn’t safe if your application depends on that data to function correctly. If the request fails, your script might continue with empty or null data, leading to crashes or incorrect results later. Always implement error handling that logs the failure and alerts you if the connection fails repeatedly so you can investigate the source of the latency.
What happens if I increase the timeout too much?
Increasing the timeout too much causes your application to become unresponsive for long periods whenever the server is slow. This creates a poor experience for users who are waiting for a page to load. It’s better to use a shorter timeout and implement a “retry” mechanism that attempts to connect again a few times before giving up entirely.
Why does it work in the browser but not in curl?
Browsers are often configured to handle redirects and cache content differently, which can mask the underlying slowness of the server. Additionally, your browser may be using a different network path or proxy settings than your command-line environment. Check your environment variables to ensure your terminal isn’t using a restricted proxy that’s causing the connection to drop.
How many retries should I allow?
A common practice is to allow 3 retries with a short delay between each attempt. This helps if the timeout was caused by a momentary “blip” in your internet connection rather than a persistent issue. If the request fails after the third attempt, you should stop and log the error for manual review, as the server is likely experiencing a significant outage.
Conclusion
Regularly auditing your network configurations ensures that your tools remain efficient as your data needs grow. If you find yourself constantly increasing timeout values, it’s a clear signal that the underlying infrastructure needs optimization rather than just more time to complete.
Related guides
