CasaOS kan apps niet laden: oplossing voor de Docker-API-versie

Als CasaOS zelf wordt geladen, maar in het gedeelte Apps alleen “Apps kunnen niet worden geladen. Probeer het later opnieuw” wordt weergegeven na een Docker-update, controleer dan eerst de logboeken van CasaOS App Management voordat u de rechten van het bestandssysteem wijzigt. In de IceWhale Community-case van november 2025 was de doorslaggevende fout niet het dashboard zelf: CasaOS App Management probeerde Docker API 1.43 te gebruiken, terwijl Docker Engine 29.0.1 minimaal API 1.44 vereiste.

Hetzelfde logboek bevatte ook rechtenfouten onder /var/run/casaos, /var/log/casaos, en /var/lib/casaos, maar de afwijzing van de Docker-API was een afzonderlijk compatibiliteitsprobleem waardoor CasaOS geen container-/appinformatie kon weergeven. De beheerders van CasaOS hebben het installatiescript later bijgewerkt zodat het met nieuwere Docker-versies werkt en compatibiliteitsafhandeling voor de API toepast. Huidige gebruikers moeten daarom beginnen met het bijgewerkte CasaOS-installatieprogramma in plaats van Docker permanent te downgraden.

De fout die het echte compatibiliteitsprobleem aan het licht bracht

De oorspronkelijke auteur meldde:

Foutreactie van daemon:
clientversie 1.43 is te oud.
Minimaal ondersteunde API-versie is 1.44,
werk uw client bij naar een nieuwere versie

De omgeving was:

Ubuntu Server;
Docker Engine 29.0.1;
Docker API 1.52;
CasaOS App Management gebouwd in oktober 2024.

Dit verklaart waarom het CasaOS-dashboard nog steeds kon worden geopend terwijl het gedeelte Apps niet werkte: de webinterface en de op Docker gebaseerde service voor appbeheer zijn verschillende lagen.

Waarom een Docker-update ervoor kon zorgen dat CasaOS geen apps meer weergeeft

Docker Engine stelt een versiegebonden API beschikbaar. Oudere beheerclients kunnen doorgaans onderhandelen met nieuwere daemons, maar Docker heeft de minimale geaccepteerde API-versie geleidelijk verhoogd.

De huidige Docker-documentatie legt uit hoe over API-versies wordt onderhandeld en vermeldt dat oudere API-versies geleidelijk worden afgeschaft of verwijderd. Zie de documentatie over de Docker Engine-API.

In dit brongeval gebruikte CasaOS App Management API 1.43, terwijl de Docker 29-daemon alles onder 1.44 weigerde. Daardoor mislukte het opsommen van apps voordat de gebruikersinterface de applijst kon weergeven.

De rechtenfouten waren echt, maar vormden niet dezelfde storing

De logboeken bevatten ook meldingen zoals:

open /var/run/casaos/app-management.url: toegang geweigerd
mkdir /var/lib/casaos/appstore/...tmp: toegang geweigerd
kan logbestand niet hernoemen ... toegang geweigerd

De auteur had al de rechten op de relevante CasaOS-mappen ingesteld en aangepast, maar de App Store werkte nog steeds niet. Dat resultaat is belangrijk: brede rechtenwijzigingen konden een incompatibiliteit met de Docker-API niet verhelpen.

Niet recursief chmod 777 of de eigendom in CasaOS-systeemmappen te wijzigen alleen omdat de gebruikersinterface aangeeft dat apps niet konden worden geladen. Lees eerst de exacte logboeken.

Wat de community destijds aanbeval

MjTech antwoordde dat dit een bekend Docker-gerelateerd probleem was en verwees de auteur naar een communityfix van BigBear voor Docker API-fouten in CasaOS.

Destijds waren veelgebruikte tijdelijke workarounds onder andere:

de minimale Docker API-versie die door de daemon wordt geaccepteerd verlagen via een systemd-override;
of tijdelijk een oudere Docker-release gebruiken die de CasaOS-client-API nog accepteerde.

Die workarounds waren waardevol in november 2025, maar mogen niet automatisch de permanente procedure voor 2026 worden, omdat het CasaOS-installatieprogramma daarna is bijgewerkt.

CasaOS heeft het installatieprogramma later bijgewerkt

In december 2025 meldde een CasaOS-maintainer op GitHub dat het installatiescript zo was aangepast dat het:

de nieuwste beschikbare Docker Engine installeren in plaats van het oude doel Docker 24.0.7;
Docker API-compatibiliteit afhandelen voor nieuwere Docker-versies;
ervoor zorgen dat CasaOS-services en ingebouwde applicaties met moderne Docker werken.

De maintainer zei specifiek dat een schone installatie of het huidige installatiescript kon worden gebruikt om het eerdere probleem waarbij Docker-apps niet werden geladen te verhelpen.

Bekijk voor de huidige bron het CasaOS-installatiescript.

Eerste huidige oplossing: gebruik het bijgewerkte CasaOS-installatieprogramma

CasaOS documenteert momenteel:

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

of:

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

Maak een back-up van belangrijke databases en configuratiebestanden van applicaties voordat je een installatieprogramma uitvoert op een bestaande server. De reparatie is bedoeld om de CasaOS-status te behouden, maar een homeserver mag nooit uitsluitend afhankelijk zijn van een reparatiescript als herstelplan.

De huidige installatie-instructies staan in de CasaOS GitHub-repository.

Controleer de API-fout voordat je een compatibiliteitsoverride toepast

Docker controleren:

docker version

Controleer vervolgens CasaOS App Management:

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

Als het logboek expliciet het volgende bevat:

clientversie 1.43 is te oud
De minimaal ondersteunde API-versie is 1.44

dan heb je te maken met dezelfde soort Docker API-fout als in de oorspronkelijke thread.

Als het logboek in plaats daarvan fouten over een volle schijf, DNS-fouten, een niet-actieve Docker-daemon, een beschadigde catalogus van de appstore of ontbrekende bestanden toont, pas dan geen API-workaround toe alleen omdat de UI-melding identiek is.

Over de historische override voor Docker API-compatibiliteit

Workarounds van de community en GitHub tijdens het incident in 2025 voegden een Docker systemd-omgevingsinstelling toe waarmee oudere client-API-versies weer werden toegestaan. Daarmee kon de app-lijst worden hersteld terwijl CasaOS API 1.43 bleef gebruiken.

Hiermee wordt de compatibiliteitsgrens van de Docker-daemon gewijzigd. Beschouw dit als een tijdelijk compatibiliteitsmechanisme voor een bevestigde mismatch tussen een oude client en een nieuwe daemon, niet als een algemene CasaOS-tuninginstelling.

De huidige Docker-documentatie legt uit dat ondersteuning voor verouderde API's in de loop der tijd verandert en raadt aan clients actueel te houden in plaats van permanent afhankelijk te zijn van oude API-versies.

Stel DOCKER_API_VERSION niet blind in voor CasaOS

Docker DOCKER_API_VERSION De variabele dwingt een client om een specifieke API-versie te gebruiken en schakelt de normale API-onderhandeling uit. Docker documenteert dit voornamelijk voor gevallen waarin een exacte API-versie vereist is of voor foutopsporing.

Dat is iets anders dan een nieuwere Docker-daemon een oudere CasaOS-client laten accepteren via diens API. Het instellen van een willekeurige API-waarde aan clientzijde kan de mismatch verergeren.

Controleer ook of Docker goed werkt

sudo systemctl status docker
docker ps

Als Docker zelf gestopt is, kan CasaOS geen actieve containers weergeven, ongeacht de API-versie.

Controleer de schijfruimte voordat je iets opnieuw installeert

Dezelfde UI-melding ‘Apps laden mislukt’ is voorgekomen in niet-gerelateerde CasaOS-gevallen waarin de systeemschijf bijna vol was. Controleer:

df -h

Een vol rootbestandssysteem kan logs, tijdelijke bestanden, updates van de App Store en de Docker-status verstoren. Ga er niet van uit dat elke identieke UI-banner dezelfde oorzaak heeft.

Veilige volgorde voor probleemoplossing

Bevestig dat het CasaOS-dashboard zelf wordt geopend.
Controleren systemctl status docker en docker ps.
Controleren df -h.
Lezen casaos-app-management logs.
Als de log de API-mismatch tussen 1.43 en 1.44 toont, gebruik dan eerst het huidige CasaOS-installatie-/herstelpad.
Gebruik alleen een override voor API-compatibiliteit wanneer de mismatch is bevestigd en het huidige herstelpad niet beschikbaar is.
Versoepel de machtigingen op CasaOS-mappen niet zonder bewijs op brede schaal.
Maak een back-up van appgegevens voordat je opnieuw installeert of systeemwijzigingen aan Docker aanbrengt.

Veelgestelde vragen over ‘Apps laden mislukt’ in CasaOS

Waarom werkt het CasaOS-dashboard wel terwijl Apps niet werken?

De UI, CasaOS-services, Docker-daemon en CasaOS App Management zijn afzonderlijke componenten. In de broncasus trad de fout specifiek op toen App Management Docker probeerde te ondervragen.

Was Docker 29 de oorzaak in de oorspronkelijke discussie?

Uit de bronlogs bleek dat Docker 29.0.1 API 1.44 vereiste, terwijl de geïnstalleerde CasaOS App Management-client API 1.43 gebruikte. Die mismatch verhinderde rechtstreeks het weergeven van apps.

Moet ik de machtigingen van CasaOS-mappen aanpassen met chmod om de pagina te repareren?

Niet zonder bewijs. De oorspronkelijke auteur had de machtigingen al aangepast, maar kreeg nog steeds de Docker-API-fout. Lees eerst de exacte servicelogs.

Moet ik Docker downgraden?

Dat was een historische workaround. CasaOS heeft het installatieprogramma later bijgewerkt voor ondersteuning van moderne Docker-compatibiliteit. Gebruik daarom eerst het huidige herstel-/installatiepad voordat je een oudere Docker-versie forceert.

Betekent ‘Apps laden mislukt’ altijd dat er sprake is van een mismatch tussen Docker-API's?

Nee. Dezelfde UI-melding kan het gevolg zijn van een gestopte Docker-daemon, een volle schijf, machtigingen, problemen met appbeheer of andere serviceproblemen. De log bepaalt de diagnose.