cURL connection refused – possible fixes

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.

curl: (7) Failed to connect to localhost port 8888: Connection refused

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''). With Django, the correct way to run a server is ./ runserver

Leave a Comment