Échec du chargement des applications dans CasaOS : correction de la version de l’API Docker

Si CasaOS se charge correctement, mais que la section Applications affiche uniquement « Échec du chargement des applications, veuillez réessayer plus tard » après une mise à jour de Docker, consultez les journaux de CasaOS App Management avant de modifier les permissions du système de fichiers. Dans le cas signalé par la communauté IceWhale en novembre 2025, l’erreur décisive ne concernait pas le tableau de bord lui-même : CasaOS App Management essayait d’utiliser l’API Docker 1.43, tandis que Docker Engine 29.0.1 exigeait au moins l’API 1.44.

Le même journal contenait également des erreurs de permission dans /var/run/casaos, /var/log/casaos, et /var/lib/casaos, mais le rejet de l’API Docker constituait une défaillance de compatibilité distincte qui empêchait CasaOS d’afficher les informations sur les conteneurs et les applications. Les mainteneurs de CasaOS ont ensuite mis à jour le script d’installation afin qu’il fonctionne avec les versions plus récentes de Docker et gère la compatibilité de l’API. Les utilisateurs actuels devraient donc commencer par utiliser l’installateur CasaOS mis à jour plutôt que de rétrograder définitivement Docker.

L’erreur qui a permis d’identifier le véritable problème de compatibilité

L’auteur original a signalé :

Réponse d’erreur du démon :
la version cliente 1.43 est trop ancienne.
La version minimale prise en charge de l’API est 1.44,
veuillez mettre à niveau votre client vers une version plus récente

L’environnement était le suivant :

Ubuntu Server ;
Docker Engine 29.0.1 ;
API Docker 1.52 ;
CasaOS App Management créé en octobre 2024.

Cela explique pourquoi le tableau de bord CasaOS pouvait toujours s’ouvrir alors que la section Applications échouait : l’interface web et le service de gestion des applications basé sur Docker sont deux couches distinctes.

Pourquoi une mise à jour de Docker peut interrompre l’affichage des applications de CasaOS

Docker Engine expose une API versionnée. Les anciens clients de gestion peuvent généralement négocier avec les nouveaux démons, mais Docker a progressivement relevé la version minimale de l’API acceptée.

La documentation actuelle de Docker explique la négociation des versions d’API et précise que les anciennes versions d’API sont progressivement dépréciées ou supprimées. Consultez la documentation de l’API Docker Engine.

Dans ce cas concret, CasaOS App Management utilisait l’API 1.43, tandis que le démon Docker 29 refusait toute version inférieure à 1.44. L’énumération des applications échouait donc avant même que l’interface puisse afficher la liste des applications.

Les erreurs de permission étaient réelles, mais ne correspondaient pas à la même défaillance

Les journaux contenaient également des messages tels que :

open /var/run/casaos/app-management.url : permission refusée
mkdir /var/lib/casaos/appstore/...tmp : permission refusée
impossible de renommer le fichier journal… permission refusée

L’auteur avait déjà créé les répertoires CasaOS concernés et ajusté leurs permissions, mais l’App Store ne fonctionnait toujours pas. Ce résultat est important : des modifications générales des permissions ne pouvaient pas résoudre une incompatibilité avec l’API Docker.

Ne le faites pas récursivement chmod 777 ou modifier la propriété des répertoires système de CasaOS simplement parce que l’interface indique que les applications n’ont pas pu être chargées. Consultez d’abord les journaux exacts.

Ce que la communauté recommandait à l’époque

MjTech a répondu qu’il s’agissait d’un problème Docker connu et a orienté l’auteur vers une solution proposée par la communauté BigBear pour les erreurs d’API Docker de CasaOS.

À l’époque, les solutions de contournement temporaires courantes comprenaient :

abaisser la version minimale de l’API Docker acceptée par le démon au moyen d’une surcharge systemd ;
ou en utilisant temporairement une ancienne version de Docker qui acceptait encore l’API client de CasaOS.

Ces solutions de contournement étaient utiles en novembre 2025, mais elles ne devraient pas automatiquement devenir la procédure permanente de 2026, car le programme d’installation de CasaOS a ensuite été mis à jour.

CasaOS a ensuite mis à jour le programme d’installation

En décembre 2025, un mainteneur de CasaOS a indiqué sur GitHub que le script d’installation avait été corrigé afin de :

installer la dernière version disponible de Docker Engine au lieu de l’ancienne version cible 24.0.7 de Docker ;
appliquer une gestion de la compatibilité de l’API Docker pour les versions plus récentes de Docker ;
permettre aux services CasaOS et aux applications intégrées de fonctionner avec les versions modernes de Docker.

Le mainteneur a précisément indiqué qu’une installation propre ou le script d’installation actuel pouvait être utilisé pour réparer le problème précédent empêchant le chargement des applications Docker dans CasaOS.

Pour consulter le code source actuel, voir le script d’installation de CasaOS.

Correctif initial actuel : utilisez le programme d’installation CasaOS mis à jour

CasaOS documente actuellement :

curl -fsSL https://get.casaos.io | sudo bash

ou :

wget -qO- https://get.casaos.io | sudo bash

Avant d’exécuter un programme d’installation sur un serveur existant, sauvegardez les bases de données et la configuration des applications importantes. La réparation est conçue pour préserver l’état de CasaOS, mais un serveur domestique ne devrait jamais dépendre d’un script de réparation comme unique plan de récupération.

Les instructions d’installation actuelles sont disponibles dans le dépôt GitHub de CasaOS.

Vérifiez l’erreur d’API avant d’appliquer une dérogation de compatibilité

Vérifiez Docker :

docker version

Examinez la gestion des applications CasaOS :

sudo systemctl status casaos-app-management
sudo journalctl -u casaos-app-management --no-pager -n 100

Si le journal contient explicitement :

la version client 1.43 est trop ancienne
La version minimale de l’API prise en charge est 1.44

vous êtes alors confronté à la même catégorie de défaillance de l’API Docker que dans le fil de discussion d’origine.

Si le journal affiche plutôt des erreurs de disque plein, des échecs DNS, un démon Docker arrêté, un catalogue de l’App Store corrompu ou des fichiers manquants, n’appliquez pas de solution de contournement de l’API simplement parce que le message de l’interface est identique.

À propos de la dérogation historique de compatibilité de l’API Docker

Les solutions de contournement proposées par la communauté et sur GitHub lors de l’incident de 2025 ont ajouté un paramètre d’environnement systemd à Docker, permettant à nouveau l’utilisation d’anciennes versions de l’API client. Cela pouvait rétablir l’affichage des applications alors que CasaOS utilisait encore l’API 1.43.

Cela modifie la limite de compatibilité du daemon Docker. Considérez-le comme un mécanisme temporaire de compatibilité pour une incompatibilité vérifiée entre un ancien client et un nouveau daemon, et non comme un paramètre de réglage générique de CasaOS.

La documentation actuelle de Docker explique que la prise en charge des anciennes API évolue au fil du temps et recommande de maintenir les clients à jour plutôt que de dépendre durablement d’anciennes versions d’API.

Ne définissez pas DOCKER_API_VERSION à l’aveugle sur CasaOS

De Docker DOCKER_API_VERSION variable force un client à utiliser une version d’API spécifique et désactive la négociation normale de l’API. Docker la documente principalement pour les cas où une version d’API précise est requise ou à des fins de débogage.

Cela diffère du fait de demander à un daemon Docker plus récent d’accepter l’API plus ancienne d’un client CasaOS. Définir une valeur d’API arbitraire côté client peut aggraver l’incompatibilité.

Vérifiez également que Docker fonctionne correctement

sudo systemctl status docker
docker ps

Si Docker lui-même est arrêté, CasaOS ne peut pas répertorier les conteneurs en cours d’exécution, quelle que soit la version de l’API.

Vérifiez l’espace disque avant de réinstaller quoi que ce soit

Le même message d’interface « Échec du chargement des applications » est apparu dans des cas CasaOS sans rapport, où le disque système était presque plein. Vérifiez :

df -h

Un système de fichiers racine plein peut empêcher le fonctionnement des journaux, des fichiers temporaires, des mises à jour de l’App Store et de l’état de Docker. Ne supposez pas que chaque bannière identique de l’interface a la même cause.

Ordre de dépannage sûr

Vérifiez que le tableau de bord CasaOS lui-même s’ouvre.
Vérifier systemctl status docker et docker ps.
Vérifier df -h.
Lire casaos-app-management journaux.
Si le journal indique l’incompatibilité entre les API 1.43 et 1.44, utilisez d’abord le parcours actuel d’installation ou de réparation de CasaOS.
N’utilisez une substitution de compatibilité d’API que lorsque l’incompatibilité est vérifiée et que le parcours actuel de réparation n’est pas disponible.
Ne relâchez pas largement les autorisations sur les répertoires CasaOS sans preuve.
Sauvegardez les données des applications avant toute réinstallation ou modification de Docker au niveau du système.

FAQ CasaOS : échec du chargement des applications

Pourquoi le tableau de bord CasaOS fonctionne-t-il alors que les applications ne fonctionnent pas ?

L’interface, les services CasaOS, le daemon Docker et CasaOS App Management sont des composants distincts. Dans le cas source, l’échec s’est produit précisément lorsque App Management a tenté d’interroger Docker.

Docker 29 était-il à l’origine du problème dans la discussion source ?

Les journaux sources indiquaient que Docker 29.0.1 exigeait l’API 1.44, tandis que le client CasaOS App Management installé utilisait l’API 1.43. Cette incompatibilité empêchait directement l’affichage de la liste des applications.

Dois-je utiliser chmod sur les dossiers CasaOS pour corriger la page ?

Pas sans preuve. L’auteur d’origine avait déjà modifié les autorisations, mais rencontrait toujours l’échec de l’API Docker. Consultez d’abord les journaux détaillés du service.

Dois-je rétrograder Docker ?

C’était une solution de contournement utilisée auparavant. CasaOS a ensuite mis à jour son programme d’installation pour prendre en charge la compatibilité avec les versions modernes de Docker ; utilisez donc le parcours actuel de réparation ou d’installation avant de forcer l’installation d’une ancienne version de Docker.

« Échec du chargement des applications » signifie-t-il toujours une incompatibilité de l’API Docker ?

Non. Le même message de l’interface peut être causé par un daemon Docker arrêté, un disque plein, des problèmes d’autorisations, des échecs de gestion des applications ou d’autres problèmes de service. Les journaux permettent d’établir le diagnostic.