cURL is the de facto standard library for making HTTP requests from the command line. It is available on most Linux distributions or macOS, and now just make its way into Windows.
In this article, you’ll learn about cURL "Connection Refused" error and discover a few possible fixes when you encounter this error.
What does cURL connection refused really mean?
"Connection Refused" is a generic error message, it means that the connection to the server has not been successfully made. The full error message looks similar to this.
The number in parentheses is the error code of libcurl
– the underlying piece of code that really power curl
, in this case, Connection Refused is error number 7. More details on libcurl
error codes can be seen at libcurl – Error Codes.
Normally, the server is to blame, but there are situations where your system configuration may have caused "Connection Refused".
If you’re a developer, chances are you misconfigured your application, have it listened on the wrong port, or something else.
Users who are working with virtualization software like Docker or Vagrant sometimes also encounter the error. The solutions will be presented in the next section of the article.
Double-check the address with a browser
Most of the time, you have to double-check the address which you’re trying to make a connection really is the correct one. Fire up a browser, try to access the original address and see whether it can connects or not.
We recommend Firefox because it uses its own proxy network stack instead of reusing system configuration, therefore you can check using your direct connection to really see through the situation without messing with proxies and stuff.
In the screenshot above, we may have to check if we started our local server at port 3000 first because the error really comes from the server.
Check your proxy configuration
Sometimes, maybe you are having a proxy server defined in your environment that blocks the connection.
All major operating system have its own GUI proxy settings, but on Linux, sometimes HTTP_PROXY
,HTTPS_PROXY
or ALL_PROXY
are left unchanged even after closing the GUI app. You need to view them in the command line to make sure that the settings are correct.
echo "$http_proxy"
echo "$https_proxy"
echo "$all_proxy"
If you just want to make sure you’re using a direct connection, run the following commands to unset these system variable all at once.
unset http_proxy https_proxy ftp_proxy rsync_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY RSYNC_PROXY ALL_PROXY
unset {http,https,ftp,rsync,all}_proxy {HTTP,HTTPS,FTP,RSYNC,ALL}_PROXY
Inspect hosts file for misconfiguration
On Linux and macOS, you can manually point a domain to an IP address without touching DNS by modifying /etc/hosts
file. Windows users can do the same, but the hosts
file is located at C:\Windows\System32\driver\etc\hosts
.
Web developers usually use this to direct local connections to localhost for easier testing. Sometimes, they leave the entries inside the hosts
file, causing strange redirects.
It’s also possible that software on your system modify the hosts
themselves, but this is not usually the case.
The solution : Empty hosts
file to see whether the problem goes away.
Force IPv4
If running curl
with -v
(verbose) option outputs something like below, you may have to either delete ::1 localhost
line from your hosts
file or force curl
to connect using IPv4.
Rebuilt URL to: localhost:3000/
Hostname was NOT found in DNS cache
Trying ::1...
Run curl
with -4
or --ipv4
to force IPv4.
curl --ipv4 http://localhost:3000
# OR
curl -4 http://localhost:3000
Docker/Vagrant users : add a proxy to reach the host
Users who work with virtualization software often need to connect to the host machine or another virtual machine from within the VM.
By default, the host isn’t available inside the Docker container. You must use the host machine IP address instead of localhost or 127.0.01. More details and configuration can be found at this stackoverflow page.
Using Flask/Django? Change the listening address
For users who is running their Dlask or Django app, please double check whether you use the correct address.
Flask apps by default only listen on the local interface, if you want your app to be available on external addresses, start it as app.run(host='0.0.0.0')
. With Django, the correct way to run a server is ./manage.py runserver 0.0.0.0:8000
.