Risolvi il problema del caricamento delle app di CasaOS dopo un aggiornamento di Docker

Se CasaOS si carica correttamente ma la sezione App mostra soltanto “Impossibile caricare le app, riprova più tardi” dopo un aggiornamento di Docker, controlla i log di CasaOS App Management prima di modificare i permessi del file system. Nel caso della community IceWhale del novembre 2025, l’errore decisivo non riguardava la dashboard in sé: CasaOS App Management tentava di utilizzare l’API Docker 1.43, mentre Docker Engine 29.0.1 richiedeva almeno l’API 1.44.

Lo stesso log conteneva anche errori di autorizzazione nelle directory /var/run/casaos, /var/log/casaos, e /var/lib/casaos, ma il rifiuto dell’API Docker era un problema di compatibilità separato che impediva a CasaOS di elencare le informazioni su container/app. In seguito, i manutentori di CasaOS hanno aggiornato lo script di installazione per funzionare con le versioni più recenti di Docker e gestire la compatibilità dell’API; gli utenti attuali dovrebbero quindi iniziare dal programma di installazione aggiornato di CasaOS invece di eseguire il downgrade permanente di Docker.

L’errore che ha identificato il vero problema di compatibilità

L’autore originale ha riferito:

Risposta di errore dal demone:
la versione client 1.43 è troppo vecchia.
La versione minima supportata dell’API è la 1.44,
aggiorna il client a una versione più recente

L’ambiente era:

• Ubuntu Server;
• Docker Engine 29.0.1;
• API Docker 1.52;
• CasaOS App Management compilato nell’ottobre 2024.

Questo spiega perché la dashboard di CasaOS poteva comunque aprirsi mentre la sezione App non funzionava: l’interfaccia web e il servizio di gestione delle app basato su Docker sono livelli distinti.

Perché un aggiornamento di Docker potrebbe interrompere l’elenco delle app di CasaOS

Docker Engine espone un’API con versionamento. I client di gestione meno recenti di solito possono negoziare con demoni più nuovi, ma Docker ha progressivamente innalzato la versione minima dell’API accettata.

La documentazione attuale di Docker spiega la negoziazione delle versioni dell’API e segnala che le versioni API più vecchie vengono gradualmente deprecate o rimosse. Consulta la documentazione dell’API Docker Engine.

In questo caso concreto, CasaOS App Management utilizzava l’API 1.43, mentre il demone Docker 29 rifiutava qualsiasi versione inferiore alla 1.44. Di conseguenza, l’elenco delle app non riusciva a essere recuperato prima ancora che l’interfaccia potesse visualizzarlo.

Gli errori di autorizzazione erano reali, ma non costituivano lo stesso problema

I log contenevano anche messaggi come:

impossibile aprire /var/run/casaos/app-management.url: autorizzazione negata
mkdir /var/lib/casaos/appstore/...tmp: autorizzazione negata
impossibile rinominare il file di log ... autorizzazione negata

L’autore aveva già creato e modificato i permessi delle directory CasaOS interessate, ma l’App Store continuava a non funzionare. Questo risultato è importante: modifiche estese ai permessi non potevano risolvere un’incompatibilità con l’API Docker.

Non in modo ricorsivo chmod 777 o modificare la proprietà tra le directory di sistema di CasaOS solo perché l’interfaccia indica che le app non sono state caricate. Leggi prima i log esatti.

Cosa consigliava la community all’epoca

MjTech ha risposto che si trattava di un problema noto legato a Docker e ha indicato all’autore una soluzione della community BigBear per gli errori dell’API Docker di CasaOS.

All’epoca, tra le soluzioni alternative temporanee più comuni c’erano:

• ridurre la versione minima dell’API Docker accettata dal demone tramite un override systemd;
• oppure utilizzare temporaneamente una versione precedente di Docker che accettava ancora l’API client di CasaOS.

Queste soluzioni alternative erano utili nel novembre 2025, ma non dovrebbero diventare automaticamente la procedura permanente del 2026, perché in seguito il programma di installazione di CasaOS è stato aggiornato.

In seguito CasaOS ha aggiornato il programma di installazione

Nel dicembre 2025, un manutentore di CasaOS ha riferito su GitHub che lo script di installazione era stato corretto in modo da:

• installare la versione più recente disponibile di Docker Engine invece del precedente obiettivo Docker 24.0.7;
• gestire la compatibilità dell’API Docker per le versioni più recenti di Docker;
• consentire ai servizi di CasaOS e alle applicazioni integrate di funzionare con Docker moderno.

Il manutentore ha specificato che un’installazione pulita o lo script di installazione attuale potevano essere utilizzati per risolvere il precedente problema di CasaOS per cui le app Docker non venivano caricate.

Per il codice sorgente attuale, consulta lo script di installazione di CasaOS.

Prima soluzione attuale: usa il programma di installazione aggiornato di CasaOS

CasaOS attualmente documenta:

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

oppure:

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

Prima di eseguire un programma di installazione su un server esistente, esegui il backup dei database delle applicazioni e della configurazione importanti. La riparazione è concepita per conservare lo stato di CasaOS, ma un home server non dovrebbe mai dipendere da uno script di riparazione come unico piano di ripristino.

Le istruzioni di installazione aggiornate sono disponibili nel repository GitHub di CasaOS.

Verifica l’errore dell’API prima di applicare qualsiasi override di compatibilità

Controlla Docker:

docker version

Quindi controlla CasaOS App Management:

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

Se il log contiene esplicitamente:

la versione client 1.43 è troppo vecchia
La versione minima dell’API supportata è 1.44

allora stai affrontando lo stesso tipo di errore dell’API Docker descritto nel thread originale.

Se il log mostra invece errori di disco pieno, errori DNS, un demone Docker non attivo, un catalogo dell’app store corrotto o file mancanti, non applicare una soluzione alternativa per l’API solo perché il messaggio dell’interfaccia è identico.

Informazioni sull’override storico della compatibilità dell’API Docker

Le soluzioni alternative della community e su GitHub durante l’incidente del 2025 aggiunsero un’impostazione dell’ambiente systemd di Docker che consentiva nuovamente versioni precedenti dell’API client. Questo poteva ripristinare l’elenco delle app mentre CasaOS utilizzava ancora l’API 1.43.

Questo modifica il limite di compatibilità del demone Docker. Consideralo un meccanismo temporaneo di compatibilità per una mancata corrispondenza verificata tra un vecchio client e un demone più recente, non un’impostazione generica di ottimizzazione di CasaOS.

La documentazione attuale di Docker spiega che il supporto alle API legacy cambia nel tempo e raccomanda di mantenere aggiornati i client, invece di dipendere permanentemente da versioni API precedenti.

Non impostare DOCKER_API_VERSION alla cieca su CasaOS

Di Docker DOCKER_API_VERSION La variabile forza un client a usare una versione API specifica e disabilita la normale negoziazione dell’API. Docker la documenta principalmente per i casi in cui è richiesta una versione API esatta o per il debug.

Questo è diverso dal fare in modo che un demone Docker più recente accetti l’API meno recente di un client CasaOS. Impostare un valore arbitrario dell’API lato client può peggiorare la mancata corrispondenza.

Verifica inoltre che Docker sia operativo

sudo systemctl status docker
docker ps

Se Docker è arrestato, CasaOS non può elencare i container in esecuzione, indipendentemente dalla versione dell’API.

Controlla lo spazio su disco prima di reinstallare qualsiasi cosa

Lo stesso messaggio dell’interfaccia «Impossibile caricare le app» è comparso in casi non correlati di CasaOS in cui il disco di sistema era quasi pieno. Controlla:

df -h

Un filesystem root pieno può compromettere i log, i file temporanei, gli aggiornamenti dell’App Store e lo stato di Docker. Non presumere che ogni banner identico dell’interfaccia abbia la stessa causa.

Ordine sicuro per la risoluzione dei problemi

1. Conferma che la dashboard di CasaOS si apra correttamente.
2. Controlla systemctl status docker e docker ps.
3. Controlla df -h.
4. Leggi casaos-app-management log.
5. Se il log mostra la mancata corrispondenza dell’API 1.43/1.44, usa prima il percorso di installazione/riparazione attuale di CasaOS.
6. Usa un override della compatibilità dell’API solo quando la mancata corrispondenza è verificata e il percorso di riparazione attuale non è disponibile.
7. Non ridurre ampiamente le autorizzazioni sulle directory di CasaOS senza prove.
8. Esegui il backup dei dati delle app prima di reinstallare o apportare modifiche a livello di sistema a Docker.

FAQ: Impossibile caricare le app in CasaOS

Perché la dashboard di CasaOS funziona mentre la sezione App no?

L’interfaccia, i servizi di CasaOS, il demone Docker e CasaOS App Management sono componenti separati. Nel caso di origine, il problema si verificava specificamente quando App Management tentava di interrogare Docker.

Docker 29 era la causa nella discussione di origine?

I log di origine mostravano che Docker 29.0.1 richiedeva l’API 1.44, mentre il client di gestione delle app di CasaOS installato usava l’API 1.43. Questa mancata corrispondenza impediva direttamente l’elenco delle app.

Devo eseguire chmod sulle cartelle di CasaOS per risolvere il problema della pagina?

Non senza prove. L’autore originale aveva già modificato le autorizzazioni, ma il problema dell’API Docker persisteva. Leggi prima i log esatti del servizio.

Devo effettuare il downgrade di Docker?

Quello era un workaround storico. In seguito CasaOS ha aggiornato il proprio programma di installazione per supportare la compatibilità con le versioni moderne di Docker, quindi usa prima il percorso di riparazione/installazione attuale, invece di forzare una versione precedente di Docker.

Il messaggio «Impossibile caricare le app» indica sempre una mancata corrispondenza dell’API Docker?

N. Lo stesso messaggio dell’interfaccia può essere causato da un demone Docker arrestato, dal disco pieno, da problemi di autorizzazioni, da errori nella gestione delle app o da altri problemi dei servizi. I log determinano la diagnosi.