Een mislukte installatie van een CasaOS-app levert meestal één eenvoudige foutmelding in de interface op: de appstore wordt niet geladen, de installatieknop van de app werkt niet of de container verschijnt maar wordt nooit geopend. De werkelijke oorzaak ligt meestal dieper dan de CasaOS-interface. CasaOS is ontworpen voor appinstallatie met één klik en implementatie van Docker-apps. Een mislukte installatie kan dus worden veroorzaakt door de servicelaag van CasaOS, het ophalen van Docker-images, DNS-resolutie, systeemtijd, CPU-architectuur of conflicten met hostpoorten.
De veiligste manier om problemen op te lossen is niet om CasaOS meteen opnieuw te installeren. Begin met het bekijken van de daadwerkelijke fout en test vervolgens laag voor laag: logboeken, netwerk en DNS, tijdsynchronisatie, CPU-architectuur, poorten en compatibiliteit met Docker.
Kort gezegd: de foutmelding van CasaOS is slechts het eerste symptoom
Een algemene melding als ‘installatie mislukt’ vertelt je dat CasaOS de implementatie niet kon voltooien, maar niet welke laag de fout veroorzaakte. De appcatalogus is mogelijk niet geladen, Docker heeft de image mogelijk niet opgehaald, de image is mogelijk niet geschikt voor je CPU-architectuur, een hostpoort is mogelijk al bezet of de container is mogelijk gestart en daarna gecrasht.
De installatie van CasaOS-apps is afhankelijk van zowel de servicelaag van CasaOS als de onderliggende Docker-omgeving. Het ophalen van Docker-images kan ook worden beïnvloed door registrytoegang, proxyinstellingen, verbindingen met lage bandbreedte en time-outs bij het downloaden van lagen.
Hanteer deze volgorde:
# 1. CasaOS-servicelogboeken bekijken
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f
# 2. Docker-containers controleren
docker ps -a
# 3. De logboeken van de mislukte container bekijken
docker logs --tail 100 <container_name_or_id>
# 4. DNS en registrytoegang testen
getent hosts github.com
getent hosts registry-1.docker.io
# 5. Systeemtijd controleren
timedatectl
# 6. CPU-architectuur controleren
uname -m
# 7. Luisterende poorten controleren
sudo ss -tulpn | grep LISTEN
Begin met logboeken voordat je instellingen wijzigt
Logboeken zijn de snelste manier om onderscheid te maken tussen een probleem met CasaOS en een probleem met Docker, het netwerk, de image of de app. De Linux-opdracht journalctl toont vermeldingen uit het systemd-logboek en de optie -u filtert logboeken voor een specifieke service-eenheid.
Begin bij CasaOS met logboeken op serviceniveau:
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f
Controleer daarna Docker. Met de opdracht docker logs van Docker haal je logboeken van een container op. Met de optie --follow kun je nieuwe uitvoer volgen terwijl de container actief is.
docker ps -a
docker logs --tail 100 <container_name_or_id>
docker logs -f <container_name_or_id>
Waar je naar zoekt:
| Aanwijzing in het logboek | Waarschijnlijke oorzaak |
|---|---|
no such host / DNS-opzoekfout |
DNS- of netwerkresolutie |
verbinding verlopen |
Netwerk, proxy, firewall, registrytoegang of lage bandbreedte |
certificate / TLS- / x509-fout |
Systeemtijd, CA-certificaten of HTTPS-onderschepping |
fout in uitvoerbaar formaat |
Verkeerde CPU-architectuur voor de image |
port is already allocated / bind: address already in use
|
Conflict met hostpoort |
minimaal ondersteunde API-versie |
API-mismatch tussen Docker-client en -daemon |
| Container wordt meteen afgesloten | Appconfiguratie, volumemachtigingen, ontbrekende omgevingsvariabele of afbeeldingsprobleem |
De regel is eenvoudig: probeer niet vijf dingen tegelijk op te lossen. Kopieer de eerste duidelijke foutregel en test vervolgens de laag waar die naar verwijst.
Controleer DNS en netwerktoegang
Als de App Store niet wordt geladen of de installatie mislukt tijdens het downloaden van een image, controleer dan DNS en uitgaand netwerkverkeer voordat je CasaOS-instellingen wijzigt. Docker haalt images op uit registers zoals Docker Hub. Als je CasaOS-host de domeinen van registers niet kan omzetten, kunnen downloads van images mislukken voordat de container zelfs maar is aangemaakt.
Gebruik tests voor naamomzetting in plaats van alleen ping te gebruiken:
getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com
De opdracht getent raadpleegt databases die zijn geconfigureerd via de Name Service Switch, waaronder de hosts-database die wordt gebruikt om hostnamen op te zoeken. Als deze opdrachten niets teruggeven, kan CasaOS mogelijk geen verbinding maken met GitHub, Docker Hub of een aangepaste appcatalogus, ook al wordt het lokale dashboard nog wel geopend.
Controleer vervolgens de resolverconfiguratie:
cat /etc/resolv.conf
Op Linux is /etc/resolv.conf het configuratiebestand voor de resolver dat voor DNS wordt gebruikt. De vermeldingen nameserver bepalen welke DNS-servers de resolver moet raadplegen. Als DNS niet werkt, kun je tijdelijk overschakelen op stabiele openbare resolvers om te controleren of dit het probleem is:
sudo nano /etc/resolv.conf
Voorbeeld van een tijdelijke test:
nameserver 1.1.1.1
nameserver 8.8.8.8
Neem geen genoegen met “het internet werkt op mijn laptop”. CasaOS draait op de server, dus de DNS-route van de server is van belang.
Controleer de systeemtijd voordat je de App Store de schuld geeft
Een onjuiste systeemtijd kan HTTPS- en certificaatvalidatieproblemen veroorzaken die lijken op problemen met de App Store of het register. Controleer voordat je de Docker- of CasaOS-configuratie wijzigt of de klok van de server goed staat en tijdsynchronisatie actief is.
timedatectl
Zoek in de uitvoer naar regels zoals:
Systeemklok gesynchroniseerd: ja
NTP-service: actief
Schakel dit in als synchronisatie is uitgeschakeld:
sudo timedatectl set-ntp true
Wacht na het inschakelen even en voer timedatectl opnieuw uit voordat je de installatie van de CasaOS-app opnieuw probeert.
Controleer of de CPU-architectuur overeenkomt met de app-image
CasaOS kan op verschillende hardwareplatforms draaien, waaronder x86-64- en ARM-apparaten. Dat betekent niet dat elke Docker-app in elke catalogus elke architectuur ondersteunt. Een Raspberry Pi, Orange Pi, kleine ARM-computer of hergebruikte Android-box kan mogelijk geen image uitvoeren die alleen voor linux/amd64 is gebouwd.
Controleer de architectuur van je host:
uname -m
Resultaat van uname -m |
Gebruikelijke betekenis |
|---|---|
x86_64 |
AMD64 / x86-64 |
aarch64 |
ARM64 |
armv7l |
32-bits ARM |
i386 / i686
|
32-bits x86 |
Containercode moet compatibel zijn met de architectuur van de host, omdat containers de kernel van de host delen. Zonder emulatie kun je geen linux/amd64-container uitvoeren op een arm64-host. Multi-platformimages lossen dit op door varianten zoals linux/amd64 en linux/arm64 onder één image aan te bieden.
Als de logboeken exec format error tonen, controleer dan de imagestatuspagina of het manifest van het register op ARM-ondersteuning. Als de image jouw platform niet ondersteunt, lossen andere CasaOS-instellingen het probleem niet op. Je hebt een image voor meerdere architecturen, een andere tag of een andere app nodig.
Controleer op poortconflicten voordat je opnieuw installeert
Sommige CasaOS-apps worden geïnstalleerd, maar de app wil nog steeds niet openen. Vaak is de container gestart, maar was de hostpoort al in gebruik of onjuist gekoppeld.
Controleer welke poorten actief luisteren:
sudo ss -tulpn | grep LISTEN
Vergelijk het resultaat vervolgens met de poortinstellingen van de app. Docker Compose definieert ports als koppelingen tussen de hostcomputer en containers. Deze koppelingen maken externe toegang tot services in containers mogelijk.
Een typische koppeling ziet er zo uit:
ports:
- "8080:80"
| Onderdeel | Betekenis |
|---|---|
8080 |
Hostpoort: wat je in je browser bezoekt |
80 |
Containerpoort: waar de app in de container op luistert |
Als een andere service hostpoort 80 al gebruikt, wijzig dan niet eerst de containerpoort. Wijzig de hostpoort in een ongebruikte waarde:
ports:
- "8080:80"
Dit is vooral belangrijk voor apps zoals reverse proxies, advertentieblokkers, dashboards en webservers, omdat deze standaard vaak poorten 80, 443, 8080 of 3000 gebruiken.
Een praktische checklist voor problemen met CasaOS-apps
Gebruik deze checklist voordat je CasaOS opnieuw installeert of containers verwijdert.
| Controle | Opdracht | Goed teken | Slecht teken |
|---|---|---|---|
| Servicelogboeken van CasaOS | journalctl -xeu casaos-app-management --no-pager |
Duidelijke installatiestroom of specifieke fout | Herhaaldelijke servicefout of Docker API-fout |
| Live logboeken van CasaOS | journalctl -u casaos -f |
UI-acties zijn zichtbaar in de logboeken | Actie in de app mislukt zonder melding of blijft zich herhalen |
| Lijst met Docker-containers | docker ps -a |
Container aangemaakt en status zichtbaar | Container ontbreekt of wordt herhaaldelijk opnieuw gestart |
| Containerlogboeken | docker logs --tail 100 <container> |
App start normaal | Afsluit-, machtigings-, configuratie- of architectuurfout |
| DNS-opzoeking | getent hosts registry-1.docker.io |
IP-adressen geretourneerd | Geen resultaat of opzoekfout |
| Image ophalen | docker pull <image>:<tag> |
Images worden gedownload | Time-out, TLS-, authenticatie- of geen overeenkomend manifest |
| Systeemtijd | timedatectl |
Klok gesynchroniseerd, NTP actief | Tijdsverschil of NTP niet actief |
| Architectuur | uname -m |
Komt overeen met het imageplatform | ARM-host met alleen een amd64-image |
| Poorten | sudo ss -tulpn | grep LISTEN |
Hostpoort niet in gebruik | Poort al in gebruik |
Veelvoorkomende foutpatronen en wat ze meestal betekenen
App Store laadt niet
Als de App Store zelf niet laadt, begin dan met DNS en netwerktoegang. CasaOS is bij normaal appgebruik afhankelijk van externe catalogus- en imagebronnen, dus de server moet deze bronnen kunnen opzoeken en bereiken.
Controleer:
getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f
Als DNS niet werkt, los dan het probleem met de resolver van de server op. Als DNS wel werkt maar Docker de images niet kan ophalen, test dan de toegang tot het register en controleer de proxy- of firewallinstellingen.
Installatie van de app mislukt tijdens het ophalen van de image
Als de installatie mislukt tijdens het ophalen van de image, kopieer dan de exacte Docker-foutmelding. Test handmatig:
docker pull <image>:<tag>
Als het handmatig ophalen mislukt door DNS- of time-outfouten, ligt het probleem niet aan de CasaOS-interface. Als het mislukt door een architectuurfout of omdat er geen overeenkomend manifest is, controleer dan het imageplatform.
App geïnstalleerd, maar kan niet worden geopend
Als de app geïnstalleerd lijkt, maar de browser deze niet kan openen, controleer dan eerst de poorten. Een onjuiste of conflicterende hostpoort kan een werkende container de indruk geven dat deze defect is.
Controleer:
docker ps
sudo ss -tulpn | grep LISTEN
Controleer daarna of de app is gekoppeld aan de hostpoort die je bezoekt.
App start en stopt onmiddellijk
Als de container bestaat maar stopt, lees dan de containerlogboeken:
docker logs --tail 100 <container>
Let op ontbrekende omgevingsvariabelen, ongeldige volumepaden, databasefouten, machtigingsfouten of exec format error.
Logboeken tonen fouten met de Docker API-versie
Als de logboeken melding maken van incompatibiliteit met de Docker API-versie, ga dan niet gokken. Voer eerst het volgende uit:
docker version
Problemen met Docker API-versies moet je beschouwen als een geavanceerd probleemoplossingsgeval. Overweeg alleen een API-overschrijving als de logboeken duidelijk een API-incompatibiliteit aangeven. Voeg niet zomaar een systemd-overschrijving toe omdat een app één keer niet werkte.
Docker- en machtigingsproblemen in CasaOS-apps
Sommige apps werken niet omdat de container wel is aangemaakt, maar niet de verwachte toegang heeft tot een volume, apparaat of netwerkpad. Dit komt vaak voor wanneer gebruikers aangepaste sjablonen installeren, appgegevens verplaatsen, externe schijven koppelen of handmatig hostmappen wijzigen.
Controleer de gekoppelde paden en logboeken van de app:
docker inspect <container_name_or_id>
docker logs --tail 100 <container_name_or_id>
Let op:
- hostmap ontbreekt;
- toegang geweigerd;
- alleen-lezenbestandssysteem;
- database kan niet worden geïnitialiseerd;
- configuratiebestand niet gevonden;
- apparaatpad ontbreekt;
- de containergebruiker kan niet naar het gekoppelde volume schrijven.
Als de fout wijst op een probleem met een volume of machtigingen, los dan eerst het pad- of machtigingsprobleem op. Als je de app opnieuw installeert zonder het onjuiste pad te wijzigen, ontstaat meestal dezelfde fout opnieuw.
Fouten die het oplossen van problemen met CasaOS lastiger maken
Fout 1: de app opnieuw installeren voordat je de logboeken leest
Opnieuw installeren kan de oorspronkelijke fout verhullen en dubbele containers, verweesde volumes of herhaaldelijk ophalen van images veroorzaken. Lees eerst de servicelogboeken van CasaOS en de Docker-containerlogboeken.
Fout 2: DNS aanpassen zonder de naamomzetting te testen
Willekeurig DNS-instellingen wijzigen kan het oplossen van problemen lastiger maken. Test eerst de naamomzetting met getent hosts. Als de server domeinen van registers of catalogi niet kan omzetten, pas dan de resolverconfiguratie aan.
Fout 3: compatibiliteit tussen ARM- en AMD64-images negeren
CasaOS kan draaien op ARM-apparaten, maar niet elke app-image ondersteunt ARM. Als je host aarch64 of armv7l is en de image alleen voor amd64 beschikbaar is, kan de installatie mislukken of kan de container stoppen met de foutmelding exec format error.
Fout 4: containerpoorten wijzigen in plaats van hostpoorten
Als in de documentatie van de app staat dat de container op poort 80 luistert, wijzig dan de interne containerpoort niet, tenzij je weet dat de app dit ondersteunt. Wijzig in plaats daarvan de hostpoort. Zo blijft het interne gedrag van de app intact en voorkom je een conflict op de host.
De installatie veilig opnieuw proberen
Probeer het opnieuw op een gecontroleerde manier nadat je de vermoedelijke oorzaak hebt gevonden:
- Noteer de exacte foutmelding.
- Los het probleem op in slechts één laag.
- Herstart de betreffende service alleen indien nodig.
- Probeer de appinstallatie opnieuw.
- Houd de logboeken in de gaten terwijl je het opnieuw probeert.
- Controleer of de container bestaat.
- Controleer of de app-poort luistert.
- Open de app via het juiste IP-adres en de juiste hostpoort.
Een veilige nieuwe poging kan er zo uitzien:
journalctl -u casaos -f
In een andere terminal:
docker ps -a
docker logs -f <container_name_or_id>
Probeer de app vervolgens opnieuw in CasaOS. Zo krijg je in één keer de actie in de gebruikersinterface, het gedrag van de CasaOS-service en de uitvoer van de Docker-container te zien.
Veelgestelde vragen
Waarom meldt CasaOS dat de appinstallatie is mislukt?
Omdat er een stap in de installatieketen is mislukt. De oorzaak kan liggen bij CasaOS-servicelogboeken, het ophalen van de Docker-image, DNS, de systeemtijd, de CPU-architectuur, poortconflicten, machtigingen of compatibiliteit met de Docker API. Begin met de logboeken en test vervolgens de stap die wordt aangegeven door de eerste echte foutmelding.
Hoe controleer ik de logboeken van een CasaOS-appinstallatie?
Begin met:
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f
Controleer vervolgens Docker:
docker ps -a
docker logs --tail 100 <container_name_or_id>
Waarom kan CasaOS de App Store niet laden?
Controleer vooral DNS, uitgaande netwerktoegang, de systeemtijd en de CasaOS-servicelogboeken. Test DNS rechtstreeks op de server met getent hosts github.com en getent hosts registry-1.docker.io en controleer daarna timedatectl en journalctl -u casaos -f.
Wat betekent exec format error in CasaOS?
Dit betekent meestal dat de Docker-image niet overeenkomt met de architectuur van je CPU. Een ARM-host probeert bijvoorbeeld mogelijk een image uit te voeren die alleen voor amd64 geschikt is. Controleer uname -m en ga na of de image je platform ondersteunt.
Hoe weet ik of een CasaOS-app is mislukt door een poortconflict?
Controleer welke poorten al luisteren:
sudo ss -tulpn | grep LISTEN
Vergelijk dit vervolgens met de hostpoort van de app. Als een andere service dezelfde hostpoort al gebruikt, wijzig je de hostpoort van de app in een ongebruikte waarde. Laat de containerpoort staan zoals de app die verwacht.
Een mislukte installatie van een CasaOS-app los je veel makkelijker op als je de melding in de gebruikersinterface als een symptoom beschouwt en niet als de oorzaak. Bekijk eerst de logboeken en controleer vervolgens DNS, de tijd, de architectuur, poorten en Docker-compatibiliteit voordat je de app opnieuw installeert of systeembrede instellingen wijzigt.
Ondersteuning en tips
Meer om te lezen

How to Keep Adult Videos on Your NAS Hidden from Family Members
Keep adult videos private on a family NAS. Check folder permissions, Plex and Jellyfin library access, thumbnails, watch history, shared TV logins and DLNA.

Wat je moet controleren voordat je een communitymodel in Transformers laadt
Gebruik de Transformers Jinja-sandboxupdate om de herkomst van modellen, chatsjablonen, externe code, geserialiseerde gewichten en geïsoleerde eerste uitvoeringen te controleren.

Voer Mirage lokaal uit: OCR en objectdetectie vanuit één afbeelding
Probeer het kleine lokale visiemodel van Cactus Compute, test OCR en objectextractie met echte invoer en krijg inzicht in de beperkingen op het gebied...



