Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP file_get_contents(): failed to open stream: Connection refused

ErrorWarning: file_get_contents(http://localhost:8000/api): Failed to open stream: Connection refused

Short answer

Connection refused means PHP reached the machine but nothing accepted the connection on that port. Test the same URL with curl from the same host first. Then check three things: the target service is not running or uses another port, localhost inside a container is the container itself, or the network requires an HTTP proxy.

  • Applies to PHP 8.3, PHP 8.4, curl 8, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Make the same request from the same machine or container with curl. If curl is refused too, PHP is not at fault.

    curl -v http://localhost:8000/api
  2. 2Match what you see, then jump to its fix

    1. 1curl also says Failed to connect ... Connection refusedNothing listens on that host and portFix
    2. 2The service works from your host browser but not from the PHP containerThe PHP code runs in a Docker container and localhost points at the containerFix
    3. 3curl works only with --proxy, direct requests to the internet are refusedThe network only allows outbound traffic through a proxyFix

What does the error look like?

  • Warning: file_get_contents(http://localhost:8000/api): Failed to open stream: Connection refused

Cause 1 of 3

Nothing listens on that host and port

1Check

libcurl describes this class of failure as a failed connect() to the host or proxy. List what listens on the port.

ss -ltnp | grep 8000

2Fix

Start the service, or correct the host and port in the URL. Do not call your own site from inside a request unless the web server has a free worker for it.

$body = file_get_contents('http://127.0.0.1:8000/api');

3Verify

curl should now return a response.

curl -I http://127.0.0.1:8000/api

Confirmed by curl.se

Did this fix it?

Cause 2 of 3

The PHP code runs in a Docker container and localhost points at the container

1Check

Inside a container, localhost is the container's own network. Containers on a user-defined network reach each other by container name, and a port reaches the outside only if it is published.

docker network ls
docker ps --format '{{.Names}} {{.Ports}}'

2Fix

Put both containers on one user-defined network and use the service's container name as the host.

docker network create appnet
docker network connect appnet api
docker network connect appnet php
# in PHP: file_get_contents('http://api:8000/api')

3Verify

Run the request from inside the PHP container.

docker exec php curl -I http://api:8000/api

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The network only allows outbound traffic through a proxy

1Check

PHP does not use a proxy unless you pass one in the stream context.

env | grep -i proxy

2Fix

Set the proxy in the http stream context. Some proxies also need request_fulluri.

$ctx = stream_context_create(['http' => [
    'proxy' => 'tcp://proxy.example.com:3128',
    'request_fulluri' => true,
]]);
$body = file_get_contents('http://example.com/', false, $ctx);

3Verify

Run the script again.

php fetch.php

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Keep service URLs in environment variables, one per environment.
  • Check the HTTP result, not only the return value, because file_get_contents returns false on failure.
  • Use container names, not localhost, between containers.

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:

Related fixes

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.