WordPress : corriger l’erreur ftp_nlist() expects parameter 1 to be resource

Lors d’une mise à jour WordPress, d’un plugin ou d’un thème, vous pouvez tomber sur cette erreur peu élégante :

Warning: ftp_nlist() expects parameter 1 to be resource, null given in /wp-admin/includes/class-wp-filesystem-ftpext.php on line 402

Warning: ftp_pwd() expects parameter 1 to be resource, null given in /wp-admin/includes/class-wp-filesystem-ftpext.php on line 226Langage du code : HTTP (http)

Avec les versions récentes de PHP, le message peut aussi apparaître sous une forme plus stricte :

ftp_nlist(): Argument #1 ($ftp) must be of type FTP\Connection, null givenLangage du code : PHP (php)

Le problème ne vient pas de ftp_nlist() lui-même. Cette fonction ne fait que révéler le souci : WordPress essaie d’utiliser sa méthode FTP pour modifier des fichiers, mais il n’a pas de connexion FTP valide. En clair, WordPress cherche la porte de service, mais personne ne lui a donné la clé.

Pourquoi WordPress utilise FTP au lieu d’écrire directement ?

Quand WordPress met à jour un plugin, un thème ou le cœur, il passe par la Filesystem API. Cette API choisit la méthode la plus adaptée pour écrire sur le disque : accès direct, FTP, FTPS ou SSH2 selon la configuration du serveur.

Si WordPress estime qu’il ne peut pas écrire directement dans les fichiers, il peut basculer vers FTP. Le problème apparaît quand cette méthode FTP est sélectionnée, mais que la connexion n’est pas correctement initialisée.

Les causes les plus fréquentes sont :

• permissions incorrectes sur les fichiers WordPress ;
• mauvais propriétaire Unix ;
• mauvais groupe Unix ;
• constante FS_METHOD mal définie ;
• identifiants FTP absents ou invalides ;
• espace disque saturé ;
• hébergement mutualisé avec restrictions spécifiques ;
• ancien conteneur Docker ou environnement local mal configuré.

Solution rapide : forcer la méthode directe

Sur un serveur correctement configuré, la solution la plus simple consiste souvent à forcer WordPress à utiliser l’accès direct au système de fichiers.

Ajoutez cette ligne dans wp-config.php, avant le commentaire /* That's all, stop editing! */ :

define( 'FS_METHOD', 'direct' );Langage du code : JavaScript (javascript)

Ensuite, relancez la mise à jour :

wp plugin update --all

Ou, pour mettre à jour uniquement un plugin :

wp plugin update nom-du-plugin

Cette solution fonctionne si PHP possède déjà les droits nécessaires pour écrire dans les fichiers WordPress. Sinon, elle ne fera que déplacer le problème vers une erreur de permission.

Vérifier la méthode utilisée par WordPress

Avec WP-CLI, vous pouvez vérifier si la constante FS_METHOD est définie :

wp config get FS_METHODLangage du code : JavaScript (javascript)

Si la commande retourne direct, WordPress est configuré pour écrire directement sur le disque.

Vous pouvez aussi vérifier les constantes FTP éventuellement présentes dans wp-config.php :

wp config list | grep -E 'FS_METHOD|FTP_'Langage du code : PHP (php)

Si vous voyez des constantes comme FTP_HOST, FTP_USER ou FTP_PASS, elles peuvent expliquer pourquoi WordPress tente d’utiliser FTP.

Vérifier les permissions WordPress

WordPress doit pouvoir écrire dans certains dossiers, notamment wp-content, wp-content/plugins, wp-content/themes et wp-content/upgrade.

Commencez par vérifier les droits :

ls -la
ls -la wp-content
ls -la wp-content/plugins
ls -la wp-content/themes

Sur une installation WordPress classique, les permissions raisonnables sont généralement :

• 755 pour les dossiers ;
• 644 pour les fichiers.

Vous pouvez corriger les dossiers avec :

find /chemin/vers/wordpress -type d -exec chmod 755 {} \;

Puis les fichiers avec :

find /chemin/vers/wordpress -type f -exec chmod 644 {} \;

Sur un serveur bien configuré avec un groupe partagé entre l’utilisateur système et le serveur web, vous pouvez utiliser des permissions plus strictes comme 750 pour les dossiers et 640 pour les fichiers. Mais sur un hébergement classique, 755 et 644 restent plus compatibles.

Évitez absolument 777. Ce n’est pas une solution, c’est une invitation avec buffet gratuit pour les ennuis.

Vérifier le propriétaire des fichiers

Si les permissions semblent correctes mais que WordPress bascule encore vers FTP, vérifiez le propriétaire Unix. C’est souvent le vrai coupable.

ls -la wp-content

Vous devez identifier l’utilisateur qui possède les fichiers et celui qui exécute PHP. Selon le serveur, PHP peut tourner avec un utilisateur comme www-data, apache, nginx, ou le nom du compte système.

Pour connaître l’utilisateur PHP-FPM sur un serveur systemd :

ps aux | grep php-fpm

Sur Ubuntu avec PHP-FPM, vous pouvez aussi inspecter la configuration du pool :

grep -R "^[[:space:]]*user\|^[[:space:]]*group" /etc/php/*/fpm/pool.d/*.confLangage du code : JavaScript (javascript)

Si votre site doit appartenir à l’utilisateur matt et au groupe www-data, vous pouvez corriger ainsi :

chown -R matt:www-data /chemin/vers/wordpress

Adaptez évidemment matt:www-data à votre serveur. Sur un hébergement mutualisé, ne lancez pas cette commande à l’aveugle. Le bon propriétaire est généralement imposé par l’hébergeur.

Tester l’écriture dans wp-content

Avant de relancer une mise à jour, testez si votre utilisateur courant peut écrire dans wp-content :

touch wp-content/test-write.tmp
rm wp-content/test-write.tmp

Ce test vérifie votre utilisateur SSH, pas forcément l’utilisateur PHP. Pour tester via WordPress, vous pouvez utiliser WP-CLI :

wp eval 'var_dump( wp_is_writable( WP_CONTENT_DIR ) );'Langage du code : JavaScript (javascript)

Si le résultat est bool(true), WordPress considère que wp-content est accessible en écriture.

Vérifier l’espace disque

Un espace disque saturé peut aussi provoquer des erreurs étranges pendant les mises à jour. Avant de démonter toute la configuration, vérifiez le disque :

df -h

Vérifiez aussi les inodes, surtout sur les hébergements avec beaucoup de fichiers cache :

df -i

Si une partition est à 100 %, WordPress ne pourra pas extraire correctement les archives de plugins ou de thèmes. Dans ce cas, libérez de l’espace avant de retenter la mise à jour.

Cas WP-CLI : relancer proprement la mise à jour

Une fois les permissions corrigées et FS_METHOD défini si nécessaire, relancez les mises à jour avec WP-CLI :

wp core update
wp plugin update --all
wp theme update --all

Si vous gérez un site WooCommerce ou un site client critique, procédez plutôt étape par étape :

wp plugin list --update=available
wp plugin update nom-du-plugin
wp cache flushLangage du code : PHP (php)

Et si le site tourne avec un cache objet persistant, purgez-le aussi selon votre stack : Redis, Memcached, cache hébergeur ou CDN.

Faut-il toujours utiliser FS_METHOD direct ?

Non. FS_METHOD en direct est adapté quand le serveur est correctement isolé et que PHP écrit avec le bon utilisateur. C’est le cas de beaucoup de serveurs modernes, VPS, conteneurs propres, hébergements WordPress managés et environnements locaux.

En revanche, sur certains hébergements mutualisés anciens ou très verrouillés, l’accès direct peut être volontairement désactivé. Dans ce cas, il vaut mieux corriger la configuration avec l’hébergeur plutôt que forcer une méthode qui contourne son modèle de sécurité.

Supprimer une mauvaise configuration FTP

Si vous n’utilisez plus FTP pour les mises à jour WordPress, vérifiez que wp-config.php ne contient pas d’anciennes constantes de ce type :

define( 'FTP_HOST', 'ftp.example.com' );
define( 'FTP_USER', 'username' );
define( 'FTP_PASS', 'password' );Langage du code : JavaScript (javascript)

Si elles sont obsolètes, supprimez-les. Des identifiants FTP périmés peuvent provoquer exactement le genre de warnings liés à ftp_nlist() et ftp_pwd().

Et surtout, ne laissez pas d’identifiants FTP en clair dans wp-config.php si vous n’en avez pas besoin. Moins il y a de secrets stockés, moins il y a de secrets à voler.

Checklist de correction

• Vérifier si FS_METHOD est défini dans wp-config.php.
• Supprimer les anciennes constantes FTP_* si elles ne servent plus.
• Vérifier les permissions : dossiers en 755, fichiers en 644.
• Vérifier le propriétaire Unix des fichiers WordPress.
• Vérifier que wp-content est accessible en écriture.
• Contrôler l’espace disque avec df -h.
• Contrôler les inodes avec df -i.
• Relancer les mises à jour avec WP-CLI.
• Éviter chmod 777, même si Stack Overflow vous regarde avec insistance.

Conclusion

L’erreur ftp_nlist() expects parameter 1 to be resource indique que WordPress tente d’utiliser FTP sans disposer d’une connexion FTP valide. La correction rapide consiste souvent à ajouter define( 'FS_METHOD', 'direct' ); dans wp-config.php.

Mais la vraie correction consiste à vérifier les permissions, le propriétaire des fichiers, l’espace disque et les anciennes constantes FTP. Une fois le système de fichiers propre, WordPress peut mettre à jour le cœur, les plugins et les thèmes sans passer par FTP. C’est plus simple, plus stable, et nettement moins bavard en warnings PHP.

Sources

• WordPress Trac — PHP warnings after updating to WordPress 5.3: ftp_nlist() and ftp_pwd()
• WordPress Developer Resources — get_filesystem_method()
• WordPress Developer Resources — Filesystem API
• WordPress Developer Resources — Changing File Permissions

Report a typo