cURL error 7 : corriger “Failed to connect to port 443”

L’erreur cURL error 7: Failed to connect to port 443 apparaît quand cURL n’arrive pas à établir une connexion réseau vers un serveur distant. Le port 443 correspond généralement à HTTPS.

Exemple fréquent avec WordPress, WP-CLI, Composer, GitHub, une API externe ou un plugin :

cURL error 7: Failed to connect to api.github.com port 443: Connection refusedLangage du code : CSS (css)

Le message peut varier légèrement :

cURL error 7: Failed to connect to example.com port 443 after 0 ms: Couldn't connect to server

Dans tous les cas, l’idée est la même : cURL a tenté d’ouvrir une connexion TCP vers l’hôte distant, mais elle a échoué. Il faut donc diagnostiquer le chemin réseau avant d’accuser WordPress, PHP ou le certificat SSL.

Que signifie cURL error 7 ?

Dans libcurl, l’erreur 7 correspond à CURLE_COULDNT_CONNECT. Elle signifie que cURL n’a pas réussi à se connecter à l’hôte distant ou au proxy configuré.

Concrètement, cela peut venir de plusieurs causes :

serveur distant indisponible ;
mauvaise résolution DNS ;
IPv6 cassée ou mal routée ;
firewall local ou distant ;
port 443 bloqué ;
proxy mal configuré ;
règle de sécurité chez l’hébergeur ;
blocage géographique ou réseau ;
service qui n’écoute pas sur le port attendu ;
conteneur Docker incapable de joindre le réseau externe.

À ne pas confondre avec une erreur de certificat TLS. Une erreur TLS arrive plus tard, quand la connexion réseau est déjà établie. Ici, la connexion elle-même échoue. On n’est pas encore au niveau du certificat. On est encore devant la porte, à tirer sur une poignée qui ne répond pas.

Exemple : WP-CLI impossible à mettre à jour

Dans mon cas, l’erreur est apparue sur un serveur hébergé en Chine continentale lors d’une mise à jour de WP-CLI :

wp cli update
Error: Failed to get url 'https://api.github.com/repos/wp-cli/wp-cli/releases?per_page=100':
cURL error 7: Failed to connect to api.github.com port 443: Connection refused.Langage du code : JavaScript (javascript)

Le problème ne venait pas de WP-CLI lui-même. Le serveur n’arrivait simplement pas à joindre api.github.com en HTTPS.

Dans ce type de situation, il faut tester la connectivité depuis le serveur concerné, pas depuis votre ordinateur. Votre poste peut joindre GitHub parfaitement, pendant que le serveur distant reste bloqué par son réseau, son DNS, son firewall ou son contexte géographique.

Codeable: trouvez les meilleurs développeurs WordPress

Étape 1 : tester l’URL avec curl en mode verbose

Commencez par lancer curl depuis le serveur qui rencontre l’erreur :

curl -v https://api.github.com/Langage du code : JavaScript (javascript)

Pour afficher seulement les en-têtes HTTP si la connexion fonctionne :

curl -I https://api.github.com/Langage du code : JavaScript (javascript)

Le mode verbose permet de voir les étapes importantes : résolution DNS, tentative IPv6, tentative IPv4, connexion au port 443, négociation TLS, puis réponse HTTP.

Si cURL bloque avant la négociation TLS, le problème est réseau. Si cURL atteint TLS puis échoue sur le certificat, ce n’est plus la même erreur.

Étape 2 : forcer IPv4

Une cause très fréquente est une IPv6 mal configurée. Le serveur possède une résolution IPv6, tente de l’utiliser, mais le routage IPv6 ne fonctionne pas correctement.

Testez avec IPv4 forcé :

curl --ipv4 -v https://api.github.com/Langage du code : JavaScript (javascript)

Ou avec la syntaxe courte :

curl -4 -v https://api.github.com/Langage du code : JavaScript (javascript)

Si la commande fonctionne en IPv4 mais échoue sans --ipv4, vous avez probablement un problème IPv6.

Pour télécharger WP-CLI en forçant IPv4 :

curl --ipv4 -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.pharLangage du code : JavaScript (javascript)

Puis :

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Cette solution est propre pour une commande ponctuelle. Elle évite d’épingler une IP dans /etc/hosts.

Kinsta: Premium Managed WordPress hosting

Étape 3 : forcer IPv6 pour confirmer le diagnostic

Pour confirmer que le problème vient d’IPv6, testez explicitement :

curl --ipv6 -v https://api.github.com/Langage du code : JavaScript (javascript)

Ou avec la syntaxe courte :

curl -6 -v https://api.github.com/Langage du code : JavaScript (javascript)

Si IPv6 échoue et IPv4 fonctionne, corrigez la configuration IPv6 du serveur, désactivez IPv6 proprement si vous ne l’utilisez pas, ou forcez IPv4 uniquement pour les outils concernés.

Le plus lu : Migrer WordPress vers un nouveau serveur avec WP-CLI et rsync

Évitez de désactiver IPv6 à la hache sur un serveur de production sans comprendre ce qui dépend de cette pile réseau. C’est souvent tentant. C’est rarement élégant.

Étape 4 : vérifier la résolution DNS

Vérifiez ensuite que le serveur résout bien le nom de domaine distant.

dig api.github.comLangage du code : CSS (css)

Pour IPv4 :

dig A api.github.comLangage du code : CSS (css)

Pour IPv6 :

dig AAAA api.github.comLangage du code : CSS (css)

Avec getent, qui reflète mieux la résolution système utilisée par beaucoup d’applications Linux :

getent hosts api.github.comLangage du code : CSS (css)

Si le DNS ne répond pas, testez un résolveur public :

dig @1.1.1.1 api.github.com
dig @8.8.8.8 api.github.comLangage du code : CSS (css)

Si les résolveurs publics fonctionnent mais pas le DNS local du serveur, regardez /etc/resolv.conf, systemd-resolved, NetworkManager ou la configuration DNS fournie par l’hébergeur.

Étape 5 : tester le port 443 avec nc

Pour savoir si le port 443 est joignable, utilisez nc :

nc -vz api.github.com 443Langage du code : CSS (css)

Un résultat positif ressemble à :

Connection to api.github.com 443 port [tcp/https] succeeded!Langage du code : CSS (css)

Si vous obtenez Connection refused, timed out ou No route to host, le problème se situe au niveau réseau, firewall, routage ou service distant.

Si nc fonctionne mais cURL échoue, regardez plutôt les paramètres cURL, le proxy, le TLS, les CA certificates ou les options passées par l’application.

Étape 6 : tester la négociation TLS avec openssl

Si le port 443 répond mais que l’application échoue encore, testez TLS directement :

openssl s_client -connect api.github.com:443 -servername api.github.comLangage du code : CSS (css)

Si la connexion TLS s’établit, vous devriez voir le certificat, la chaîne TLS et une ligne de vérification. Si cette étape échoue, le problème peut venir d’un proxy, d’un filtrage TLS, d’une inspection réseau ou d’un vieux système incapable de négocier correctement avec le serveur distant.

Attention : une erreur TLS n’est pas exactement une cURL error 7. libcurl réserve aussi des codes spécifiques pour les erreurs SSL/TLS. Par exemple, l’erreur 35 signale un problème pendant la négociation SSL/TLS, tandis que l’erreur 60 signale un échec de vérification du certificat distant.

Étape 7 : vérifier les firewalls locaux

Sur le serveur, vérifiez les règles de firewall sortant. Beaucoup d’admins regardent seulement les ports entrants, alors que cURL a besoin d’une connexion sortante vers le port 443.

Avec UFW :

sudo ufw status verbose

Avec nftables :

sudo nft list rulesetLangage du code : PHP (php)

Avec iptables sur une ancienne configuration :

sudo iptables -S
sudo iptables -L -n -v

Cherchez les règles qui bloquent OUTPUT, les ports 80/443, les connexions vers certaines plages IP, ou les connexions depuis l’utilisateur qui exécute PHP, WP-CLI ou Composer.

Étape 8 : vérifier le firewall ou réseau de l’hébergeur

Certains hébergeurs appliquent aussi des règles sortantes au niveau réseau. Dans ce cas, votre firewall local peut être ouvert, mais la connexion reste bloquée plus haut.

À vérifier dans le panel hébergeur :

règles de firewall réseau ;
security groups ;
ACL sortantes ;
filtrage anti-abus ;
blocage géographique ;
proxy obligatoire ;
NAT ou passerelle sortante ;
restrictions propres aux datacentres ou pays.

Sur des serveurs hébergés dans certains pays ou réseaux très filtrés, GitHub, Google, npm, Packagist ou certaines APIs peuvent être partiellement injoignables. Dans ce cas, le problème n’est pas votre commande. C’est le chemin réseau. Toujours sympathique quand l’infrastructure décide de faire de la géopolitique.

Le plus lu : Trouver des fichiers sur Internet avec Google et les bons opérateurs

Étape 9 : vérifier un proxy mal configuré

cURL peut utiliser un proxy via variables d’environnement ou configuration. Un proxy mort ou incorrect peut provoquer une erreur de connexion.

Vérifiez les variables :

env | grep -Ei 'http_proxy|https_proxy|all_proxy|no_proxy'Langage du code : JavaScript (javascript)

Si un proxy apparaît, testez sans proxy :

HTTPS_PROXY= HTTP_PROXY= ALL_PROXY= curl -v https://api.github.com/Langage du code : JavaScript (javascript)

Vérifiez aussi le fichier de configuration cURL :

cat ~/.curlrc

Un vieux proxy oublié dans ~/.curlrc peut transformer une commande simple en chasse au fantôme.

Étape 10 : vérifier le fichier /etc/hosts

Si /etc/hosts contient une entrée statique pour le domaine distant, cURL peut viser une ancienne IP qui ne répond plus.

grep -n 'api.github.com' /etc/hostsLangage du code : JavaScript (javascript)

Si vous trouvez une entrée de ce type :

13.250.94.254 api.github.comLangage du code : CSS (css)

vérifiez qu’elle est encore nécessaire. Dans la plupart des cas, il vaut mieux la supprimer et laisser le DNS faire son travail.

Modifier /etc/hosts peut dépanner temporairement dans un environnement très filtré, mais ce n’est pas une solution durable pour des services derrière CDN ou load balancing. Une IP peut changer, disparaître, ou ne plus servir le bon certificat.

Faut-il utiliser /etc/hosts comme solution ?

Dans l’ancien cas traité ici, ajouter une IP de api.github.com dans /etc/hosts avait permis de contourner le problème rapidement. Mais aujourd’hui, je recommande cette méthode seulement comme dépannage très temporaire.

Si vous devez vraiment le faire, commencez par récupérer une IP actuelle depuis le serveur :

dig A api.github.com +shortLangage du code : CSS (css)

Puis éditez /etc/hosts :

sudo nano /etc/hosts

Ajoutez une ligne temporaire :

IP_ACTUELLE api.github.comLangage du code : CSS (css)

Mais documentez-la, surveillez-la, et supprimez-la dès que possible. Un /etc/hosts oublié, c’est une bombe lente. Pas spectaculaire, mais très pénible le jour où elle explose.

Configurer curl pour utiliser IPv4 par défaut

Si vous savez que votre environnement IPv6 est cassé et que vous devez avancer, vous pouvez forcer IPv4 dans la configuration utilisateur de cURL :

echo '--ipv4' >> ~/.curlrcLangage du code : PHP (php)

Cette méthode s’applique aux commandes curl lancées par cet utilisateur. Elle ne corrige pas forcément PHP, WordPress, Composer ou WP-CLI si ces outils utilisent libcurl directement sans lire ~/.curlrc.

Pour une correction serveur, mieux vaut corriger le routage IPv6 ou la priorité de résolution au niveau système. Mais pour un VPS isolé et un besoin immédiat, ~/.curlrc peut dépanner.

Cas WordPress : cURL error 7 dans Santé du site

Dans WordPress, l’erreur peut apparaître dans Outils → Santé du site, dans un plugin, ou lors d’une mise à jour. WordPress utilise l’API HTTP interne, qui peut s’appuyer sur cURL selon l’environnement PHP.

Commencez par tester depuis le serveur :

curl -I https://api.wordpress.org/
curl -I https://downloads.wordpress.org/
curl -I https://api.github.com/Langage du code : JavaScript (javascript)

Si ces commandes échouent, le problème est sous WordPress : DNS, firewall, proxy, IPv6, hébergeur ou réseau.

Si elles fonctionnent en ligne de commande mais pas dans WordPress, vérifiez :

l’utilisateur PHP-FPM ;
les restrictions réseau du serveur web ;
SELinux ou AppArmor selon la distribution ;
un plugin de sécurité ;
un proxy défini dans wp-config.php ;
les constantes WordPress WP_PROXY_HOST, WP_PROXY_PORT, WP_PROXY_USERNAME, WP_PROXY_PASSWORD et WP_PROXY_BYPASS_HOSTS.

Un test CLI réussi ne garantit pas toujours que PHP-FPM ou Apache a le même accès réseau. Même machine, autre utilisateur, autre environnement. Classique. Agaçant. Très Linux.

Cas WP-CLI : mettre à jour sans GitHub API

Si wp cli update échoue à cause de api.github.com, vous pouvez télécharger le PHAR directement, en forçant IPv4 si nécessaire :

curl --ipv4 -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --infoLangage du code : JavaScript (javascript)

Si GitHub est totalement inaccessible depuis le serveur, téléchargez le fichier depuis une autre machine, vérifiez-le, puis transférez-le via SSH/SCP. Ce n’est pas aussi élégant qu’une mise à jour directe, mais c’est souvent plus sûr qu’un empilement de contournements réseau douteux.

Le plus lu : PHP : résoudre l'erreur "PHP Fatal error: Uncaught Error: Class DOMDocument"

Cas Docker : cURL fonctionne sur l’hôte mais pas dans le conteneur

Dans Docker, testez depuis le conteneur lui-même :

docker compose exec app curl -v https://api.github.com/Langage du code : JavaScript (javascript)

Le nom du service peut être app, php, wordpress ou autre.

Vérifiez ensuite :

DNS Docker ;
réseau Docker Compose ;
proxy transmis au conteneur ;
règles firewall sur l’hôte ;
résolution IPv6 dans le conteneur ;
image PHP qui ne contient pas les bons certificats CA.

Si le conteneur ne dispose même pas de curl, installez-le temporairement ou utilisez wget, openssl, busybox nc selon l’image. Les images minimales sont rapides, mais elles adorent retirer l’outil qu’il vous faut au moment exact où vous en avez besoin.

Différence entre Connection refused, timed out et no route to host

Le détail du message aide beaucoup.

Message	Sens probable	Piste
`Connection refused`	La machine répond, mais rien n’accepte la connexion sur ce port, ou un firewall rejette activement	Service distant, port, firewall
`Connection timed out`	Aucune réponse exploitable	Firewall silencieux, routage, filtrage réseau
`No route to host`	Le système ne sait pas atteindre la destination	Routage, passerelle, réseau
`Could not resolve host`	DNS échoué	Résolveur DNS, domaine, `/etc/resolv.conf`
`SSL certificate problem`	Connexion établie, mais certificat refusé	CA certificates, horloge système, TLS

Ne traitez donc pas tous les messages cURL de la même manière. Le numéro d’erreur aide, mais le texte complet est souvent encore plus utile.

Résumé des commandes de diagnostic

Objectif	Commande
Tester l’URL en détail	`curl -v https://api.github.com/`
Forcer IPv4	`curl --ipv4 -v https://api.github.com/`
Forcer IPv6	`curl --ipv6 -v https://api.github.com/`
Tester DNS IPv4	`dig A api.github.com`
Tester DNS IPv6	`dig AAAA api.github.com`
Tester résolution système	`getent hosts api.github.com`
Tester le port 443	`nc -vz api.github.com 443`
Tester TLS	`openssl s_client -connect api.github.com:443 -servername api.github.com`
Voir les proxies	`env \| grep -Ei 'http_proxy\|https_proxy\|all_proxy\|no_proxy'`
Vérifier cURL config	`cat ~/.curlrc`
Vérifier /etc/hosts	`grep -n 'api.github.com' /etc/hosts`
Vérifier UFW	`sudo ufw status verbose`
Vérifier nftables	`sudo nft list ruleset`

Checklist de correction

Tester l’URL avec curl -v depuis le serveur concerné.
Comparer curl --ipv4 et curl --ipv6.
Vérifier la résolution DNS avec dig et getent.
Tester le port 443 avec nc.
Tester TLS avec openssl s_client.
Vérifier les proxies dans l’environnement.
Vérifier ~/.curlrc et /etc/hosts.
Contrôler firewall local et firewall hébergeur.
Tester depuis un autre réseau ou un autre serveur.
Éviter les entrées /etc/hosts permanentes pour des services CDN.
Pour WordPress, tester aussi depuis PHP ou WP-CLI, pas seulement depuis le shell.

Ce qu’il ne faut pas faire

Ne désactivez pas la vérification SSL pour résoudre une cURL error 7.
Ne modifiez pas /etc/hosts durablement avec une IP de CDN.
Ne supposez pas que GitHub, WordPress.org ou l’API distante est en panne sans tester depuis plusieurs réseaux.
Ne corrigez pas WordPress si le serveur ne peut pas joindre l’URL avec curl.
Ne confondez pas erreur de connexion, erreur DNS et erreur TLS.
Ne négligez pas IPv6 : une IPv6 cassée peut faire perdre beaucoup de temps.

La mauvaise correction classique consiste à ajouter -k ou --insecure à cURL. Cela désactive la vérification du certificat, mais cela ne règle pas une erreur 7. Si la connexion TCP échoue, cURL n’arrive même pas assez loin pour vérifier proprement le certificat.

À retenir

cURL error 7 signifie que cURL n’a pas réussi à se connecter à l’hôte ou au proxy.
Sur le port 443, le problème concerne généralement une connexion HTTPS impossible à établir.
Commencez par curl -v, puis comparez IPv4 et IPv6.
Vérifiez DNS, firewall, proxy, routage et réseau hébergeur.
Utilisez /etc/hosts seulement comme dépannage temporaire.
Pour WP-CLI, forcer IPv4 peut suffire si IPv6 est cassée.
Pour WordPress, testez depuis le serveur et depuis le contexte PHP si nécessaire.

En résumé, cURL error 7: Failed to connect to port 443 n’est pas une erreur magique de WordPress ou de PHP. C’est un échec de connexion réseau. La bonne méthode consiste à tester la résolution DNS, IPv4/IPv6, le port 443, les firewalls, le proxy et le contexte d’exécution. Ensuite seulement, appliquez un correctif ciblé : forcer IPv4, corriger le DNS, ouvrir le firewall, réparer IPv6, retirer un proxy cassé ou contourner proprement un réseau filtré.

Sources

Au passage, le filtrage du Great Firewall of China rend également chaque opération et commande assez délicate.

Report a typo

Shares2Facebook Tweet Pin LinkedIn