Maaz Zindani

Loading the index…

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

Guzzle or Http::get fails with cURL error 6 in Laravel

ErrorcURL error 6: Could not resolve host: api.example.com (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)

Short answer

cURL error 6 means the machine running PHP could not turn the host name in the URL into an IP address. The request never left your server. Print the exact URL being called first. It is usually empty or wrong because env() returned null, or the container has no working DNS.

  • Applies to Laravel 12, PHP 8.3, Guzzle 7, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on Guzzle's debug output for one call. It prints the exact host libcurl tried to look up, which shows at once whether the URL is wrong or the name server is.

    php artisan tinker
    >>> Http::withOptions(['debug' => true])->get('https://api.example.com/health');
  2. 2Match what you see, then jump to its fix

    1. 1The debug output shows a host like an empty string, 'http:' or a name with no domain partThe host in the URL is empty or wrong because env() returns nullFix
    2. 2The URL is correct and it resolves on your laptop, but fails only inside Docker or SailThe container cannot reach a DNS serverFix
    3. 3getent prints nothing for the host, even on the plain serverThe host name does not exist from where the code runsFix

What does the error look like?

  • cURL error 6: Could not resolve host: api.example.com (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)
  • Illuminate\Http\Client\ConnectionException: cURL error 6: Could not resolve host
  • GuzzleHttp\Exception\ConnectException: cURL error 6

Cause 1 of 3

The host in the URL is empty or wrong because env() returns null

1Check

Look at where the base URL comes from. If the code calls env('API_URL') outside a config file, the value becomes null once the configuration is cached.

grep -rn "env('API" app/ routes/
php artisan config:show services

2Fix

Read the value in a config file (for example config/services.php) and use config('services.api.url') in your code. Then rebuild the cache.

// config/services.php
'api' => ['url' => env('API_URL')],

// in your code
Http::baseUrl(config('services.api.url'))->get('/health');

php artisan config:cache

3Verify

Run the call again and confirm the URL printed by debug has the full host.

php artisan tinker --execute="echo config('services.api.url');"

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

The container cannot reach a DNS server

1Check

Ask the container itself to look the host up. A container on the default bridge network gets a copy of the host's /etc/resolv.conf; a container on your own network uses Docker's built-in DNS at 127.0.0.11.

docker compose exec app cat /etc/resolv.conf
docker compose exec app getent hosts api.example.com

2Fix

Fix DNS on the Docker host first, because containers use the host's DNS servers by default. If you must, override it per container with --dns.

docker run --dns 1.1.1.1 --dns 8.8.8.8 my-image

3Verify

Start the container again and repeat the lookup.

docker run --rm --dns 1.1.1.1 my-image getent hosts api.example.com

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The host name does not exist from where the code runs

1Check

Error 6 is libcurl's code for a host it could not resolve. Test the same name outside PHP, from the same machine.

getent hosts api.example.com
curl -sS -o /dev/null -w "%{http_code}\n" https://api.example.com/

2Fix

Correct the spelling or the environment (a staging host used on a machine that is not on the private network). If the name is right and public, the DNS record or your server's resolver is the thing to fix.

# set the correct host in .env, then
php artisan config:cache

3Verify

curl reaches the host and returns an HTTP status.

curl -sS -I https://api.example.com/

Confirmed by curl.se

Did this fix it?

How do I stop it coming back?

  • Call env() only inside config files; use config() everywhere else, so cached configuration cannot blank a URL.
  • Keep API base URLs in config/services.php with one clear key per service.
  • Use the Http client's debug option when you add a new integration, to see the real URL once.

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

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

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.