Errori comuni di WebODM e OpenDroneMap: significato e rimedi

Come usare questo catalogo#

Quando un'elaborazione fallisce, l'interfaccia mostra lo stato "Failed" e un messaggio breve. Quello utile è più in basso: apri il log del task, leggi le ultime cinquanta righe e cerca Error, Killed, Traceback o il nome di un file. Poi confronta con le voci di questa pagina. Da riga di comando il log è direttamente nel terminale.

Ogni errore ha lo stesso schema: cosa significa, causa probabile, rimedio. Gli errori del motore (memoria, disco, dataset) valgono per ODX e ODM allo stesso modo. I comandi riportati per intero sono quelli di WebODM con Docker (webodm.sh), perché la scheda di riferimento di questo sito li contiene verificati; per OpenDroneMap Desktop il rimedio è quasi sempre "consulta il supporto incluso e docs.opendronemap.org", perché la nonprofit distribuisce l'interfaccia solo tramite installer e questo sito non riporta comandi non verificati; per ODM e NodeODM da Docker indichiamo il comando quando esiste nella scheda o il rimando. Dove un messaggio cambia da versione a versione, descriviamo il sintomo.

Dopo ogni correzione non ripartire da zero: il pulsante "Restart" nella scheda del task riprende da una fase precisa (l'equivalente di --rerun-from) e fa risparmiare ore sui dataset grandi. Vale per entrambe le interfacce.

1. Errori di risorse#

Out of memory, processo ucciso ("Killed")#

Cosa significa. Il motore ha chiesto più RAM di quella disponibile e il sistema lo ha terminato. Nel log vedi Killed, MemoryError, std::bad_alloc o un'interruzione a metà fase, spesso durante matching, densificazione (MVS) o mesh.

Causa probabile. Troppe immagini per la RAM che hai. La scala della documentazione WebODM è 40 immagini → 4 GB; 250 → 16 GB; 500 → 32 GB; 1.500 → 64 GB; 5.000 → 256 GB; la documentazione ODM indica 4 GB minimi per 100–200 immagini e 16 GB consigliati (Requisiti hardware affianca le due dichiarazioni). Su Docker Desktop (Windows e macOS, compreso OpenDroneMap Desktop su macOS) conta la RAM assegnata a Docker, non quella del computer.

Rimedio. Vale per entrambi i motori.

1. Docker Desktop: Settings → Resources → memoria ad almeno 4 GB, meglio 16 GB. Riavvia Docker e l'interfaccia.
2. Riduci il carico: ridimensiona le immagini in upload ("Resize images"), abbassa --feature-quality a medium e --pc-quality a medium o low, attiva --optimize-disk-space.
3. Oltre le 1.000 immagini usa --split e --split-overlap: Dataset grandi e split-merge.
4. Se si ripete, servono più RAM o un server: Requisiti hardware.

"No space left on device"#

Cosa significa. Il disco su cui il motore scrive è pieno. Il messaggio è letterale e compare nel log del task o del container.

Causa probabile. Su Docker Desktop il disco virtuale predefinito è di 20 GB e si riempie con due o tre progetti. Su Linux il disco può essere pieno davvero, oppure i progetti sono sulla partizione di sistema.

Rimedio.

1. Docker Desktop: Settings → Resources → aumenta il disco virtuale.
2. Elimina dall'interfaccia i task che non servono.
3. Sposta i dati su un disco capiente. Il modo dipende dalla linea.

./webodm.sh restart --media-dir /storage/media --node-dir /storage/node

Verifica con df -h che la partizione abbia spazio.

Immagini troppo grandi o troppo pesanti#

Cosa significa. Il task rallenta molto o fallisce per memoria già nelle prime fasi, con immagini da 40–60 megapixel o file di decine di megabyte.

Causa probabile. L'estrazione delle feature lavora sull'immagine intera. Immagini enormi moltiplicano RAM e tempo senza migliorare il risultato, perché il limite reale è il GSD del volo.

Rimedio. Attiva il ridimensionamento in upload (lato di 2.048 o 4.096 pixel) o ridimensiona prima le foto. Piena risoluzione solo con RAM abbondante e un motivo preciso. Vedi Ottimizzare tempi e memoria.

2. Errori sul dataset#

"Cannot process dataset"#

Cosa significa. Il motore ha rifiutato il dataset prima di iniziare la ricostruzione vera e propria. È il messaggio più generico e nasconde tre cause diverse, che il log distingue.

Causa probabile e rimedio.

Poche immagini valide. Se hai caricato poche foto, o molte non sono JPEG/TIFF ma video, RAW o file danneggiati, il conteggio scende sotto la soglia minima. Rimedio: carica solo JPG (o TIFF per il multispettrale), almeno alcune decine, e controlla che si aprano.

EXIF mancanti. Il log non trova i metadati della camera (focale, sensore) o le coordinate GPS. Succede con foto passate da app di messaggistica, esportate da un editor o estratte da un video. Rimedio: riparti dai file originali della scheda SD. Senza GPS il dataset si elabora ma non è georeferenziato; senza dati camera puoi provare --camera-lens esplicito, con risultato incerto.

Poche feature. Il numero di punti caratteristici è insufficiente: superfici uniformi (acqua, neve, tetti bianchi), foto sfocate o sovraesposte. Rimedio: --feature-quality high o ultra, --min-num-features più basso con prudenza, oppure rivola con più sovrapposizione e luce migliore. Vedi Casi particolari.

"Reconstruction failed" o poche immagini ricostruite#

Cosa significa. La fase Structure from Motion (SfM) non è riuscita ad allineare le immagini, oppure ne ha allineato solo una parte. Nel report di qualità la voce "Reconstructed Images" è molto inferiore al numero di immagini caricate.

Causa probabile. Sovrapposizione insufficiente (sotto il 60–65 % laterale), voli spezzati in blocchi che non si toccano, cambio di quota o di ottica a metà volo, foto sfocate. Su dataset misti nadir più obliqui capita che i due gruppi non si "parlino".

Rimedio.

1. Apri la mappa delle sovrapposizioni nel report: le zone rosse mostrano dove il volo era povero di foto. Vedi Leggere il report di qualità.
2. Prova --matcher-neighbors esplicito (12 o 16) e --feature-quality high.
3. Con file --geo o GPS affidabile, --sfm-algorithm triangulation aiuta su blocchi regolari; planar è per voli nadir su terreno quasi piano.
4. Se il volo era incompleto, rivola: Acquisire le immagini.

3. Errori di collegamento tra interfaccia e nodo#

Nodo di elaborazione offline / nessun nodo disponibile#

Cosa significa. Nell'interfaccia il nodo compare con lo stato "Offline", oppure avviando un task l'interfaccia avvisa che non ci sono nodi di elaborazione disponibili e il task non parte.

Causa probabile. Il container o il processo del nodo (NodeODX nella linea WebODM, NodeODM nella linea OpenDroneMap) non è partito, è crollato per mancanza di memoria, oppure la porta su cui l'interfaccia lo cerca non risponde.

Rimedio. Il primo controllo è comune alle installazioni Docker di entrambe le linee: verifica che i container siano in esecuzione.

docker ps

Se il nodo manca, leggi docker logs <nome_container>. Poi riavvia in modo pulito, con il comando della tua linea.

./webodm.sh stop
./webodm.sh start

Infine, in entrambe le interfacce: nell'elenco dei nodi → nodo → Edit verifica hostname e porta; per il nodo locale lascia i predefiniti. Con un nodo remoto o con Lightning il problema è di rete: vedi la voce seguente e NodeODX/NodeODM e ClusterODX/ClusterODM.

Task bloccato in "Queued"#

Cosa significa. Il task resta in coda per molto tempo senza mai passare a "Running".

Causa probabile. Il nodo è occupato da un altro task (ne elabora uno alla volta per impostazione predefinita), è online ma non accetta lavoro, oppure la richiesta non è stata consegnata.

Rimedio. Se c'è un altro task in "Running", attendi. Altrimenti riavvia: ./webodm.sh restart con WebODM in Docker; riapertura dell'applicazione con gli installer nativi di WebODM e con OpenDroneMap Desktop. Se resta in coda, cancellalo e ricrealo: le immagini caricate restano nell'interfaccia.

Errore di connessione a WebODM Lightning (linea WebODM)#

Cosa significa. Hai aggiunto WebODM Lightning, il nodo cloud della linea WebODM, come nodo di elaborazione, ma WebODM non riesce a raggiungerlo o il nodo compare offline a intermittenza. La linea OpenDroneMap non ha un servizio cloud proprio alla data di verifica, quindi questa voce non la riguarda.

Causa probabile. La documentazione WebODM indica la risoluzione dei nomi: DNS che non risolve il dominio di Lightning o file hosts con voci sbagliate. In ufficio può essere un proxy o un firewall in uscita.

Rimedio. Verifica che il computer raggiunga webodm.net da un browser. Controlla il file hosts (/etc/hosts su Linux e macOS, C:\Windows\System32\drivers\etc\hosts su Windows) e rimuovi voci manuali su WebODM o Lightning. Dietro un proxy aziendale, configura Docker per usarlo. Per credenziali e crediti: webodm.net.

4. Errori di installazione e avvio#

Porta 8000 già occupata#

Cosa significa. All'avvio l'interfaccia segnala che non può mettersi in ascolto sulla porta 8000, oppure aprendo http://localhost:8000 vedi un'applicazione diversa.

Causa probabile. Un altro programma usa la porta 8000: un server di sviluppo, un'altra istanza dell'interfaccia, un servizio di sistema. Caso frequente dopo la separazione: WebODM e OpenDroneMap Desktop installati sulla stessa macchina, entrambi con la porta predefinita ereditata dall'origine comune.

Rimedio. Individua il processo e chiudilo. Su Linux e macOS:

sudo lsof -i :8000

Su Windows, in PowerShell:

netstat -ano | findstr :8000

Se non puoi liberare la porta, cambia quella dell'interfaccia.

Per tenere entrambe le linee sulla stessa macchina senza conflitti di porte, volumi e nomi di container, vedi Repository, immagini Docker e migrazioni.

Permessi Docker su Linux ("permission denied" sul socket Docker)#

Cosa significa. Lanciando ./webodm.sh start, oppure docker run con opendronemap/odm o opendronemap/nodeodm, ricevi un errore di permesso negato che cita docker.sock o il demone Docker.

Causa probabile. Il tuo utente non è nel gruppo docker e può usare Docker solo con sudo; gli script e i comandi non vanno lanciati con sudo.

Rimedio. Aggiungi l'utente al gruppo e apri una nuova sessione. Il comando è di Docker, non del software di fotogrammetria, quindi vale per entrambe le linee:

sudo usermod -aG docker $USER
# uscire e rientrare nella shell

Poi rilancia il tuo comando (./webodm.sh start per WebODM; il tuo docker run per la linea OpenDroneMap). Verifica con docker ps senza sudo. Dettagli in Linux con Docker.

Windows: virtualizzazione (VT-x/AMD-V) disabilitata#

Cosa significa. Docker Desktop non parte, oppure lo script webodm.sh fallisce subito con un errore che cita la virtualizzazione, WSL o l'hypervisor.

Causa probabile. La virtualizzazione hardware è spenta nel BIOS/UEFI, caso frequente sui portatili aziendali.

Rimedio. Riavvia, entra nel BIOS/UEFI e attiva "Intel Virtualization Technology (VT-x)" o "SVM Mode" (AMD-V); il nome cambia con il produttore. Dopo il riavvio, Gestione attività → Prestazioni → CPU deve indicare "Virtualizzazione: Abilitato". Guida: WebODM su Windows con Docker e WSL2.

Windows: WSL2 non attivo#

Cosa significa. Docker Desktop avvisa che WSL2 non è installato o non è aggiornato; WebODM non si avvia.

Causa probabile. La funzionalità "Sottosistema Windows per Linux" non è attiva o è alla versione 1.

Rimedio. In PowerShell da amministratore:

wsl --install
wsl --update
wsl --set-default-version 2

Riavvia e riapri Docker Desktop, che deve indicare il backend WSL2 attivo. Se preferisci evitare Docker, su Windows 11 entrambe le linee offrono un installer nativo: WebODM (gratuito) e OpenDroneMap Desktop (a pagamento), a confronto in Windows con l'installer e in Installazione a confronto.

Ho clonato github.com/OpenDroneMap/WebODM e ora punta altrove#

Cosa significa. Hai seguito una guida scritta prima dell'aprile 2026, hai clonato github.com/OpenDroneMap/WebODM e ti accorgi che Git ha scaricato da github.com/WebODM/WebODM; oppure git remote -v in una vecchia installazione mostra ancora l'indirizzo sotto l'organizzazione OpenDroneMap e non sai cosa succede all'aggiornamento.

Causa probabile. Dal 6 aprile 2026 WebODM si è separato da OpenDroneMap e il repository dell'interfaccia è github.com/WebODM/WebODM. L'indirizzo storico reindirizza al nuovo (verificato il 2 settembre 2026). Il reindirizzamento significa che quel repository contiene WebODM, l'interfaccia della linea WebODM, con il motore ODX: non è un repository della nonprofit. La nonprofit non pubblica un repository aperto della propria interfaccia OpenDroneMap Desktop, che si ottiene dall'installer di opendronemap.org/download. Le immagini Docker opendronemap/webodm_webapp e opendronemap/nodeodm non sono più aggiornate dal creatore di WebODM.

Rimedio. Dipende da quale linea vuoi usare; nessuna delle due è "quella giusta" per tutti.

git remote set-url origin https://github.com/WebODM/WebODM.git
./webodm.sh update

Come passare da una linea all'altra in entrambe le direzioni, e come riconoscere quali immagini sta usando la tua installazione, è spiegato in Repository, immagini Docker e migrazioni.

L'aggiornamento non porta novità o non parte#

Cosa significa. Hai aggiornato ma la versione mostrata è la stessa, oppure dopo l'aggiornamento il software non si avvia.

Causa probabile e rimedio. Dipende dalla linea e dal tipo di installazione.

Procedura completa in Aggiornare, backup e ripristino.

5. Errori di uso quotidiano#

Upload lento o interrotto#

Cosa significa. Il caricamento delle immagini procede a singhiozzo, si ferma a una certa percentuale o il browser segnala un errore di rete.

Causa probabile. Connessione instabile verso il server (tipico con WebODM su VPS), browser in standby, dataset da molti gigabyte, proxy con timeout brevi.

Rimedio. Usa un browser aggiornato e tieni la scheda attiva. Su server remoto, il ridimensionamento in upload riduce i megabyte da trasferire. Per dataset molto grandi, copia le immagini sul server via scp/rsync ed elabora da lì: ODM e ODX da riga di comando. Se l'upload si interrompe, l'interfaccia conserva il task in attesa: riaprilo e riprova.

Password amministratore dimenticata#

Cosa significa. Non riesci più ad accedere all'interfaccia con l'utente admin.

Causa probabile. Password persa o installazione ereditata da un collega.

Rimedio. Il comando di reset dipende dalla linea.

./webodm.sh start && ./webodm.sh resetadminpassword nuovapassword

Quando chiedere aiuto#

Se l'errore non è in questa pagina, raccogli linea e versione (WebODM o OpenDroneMap Desktop; ODX o ODM, con l'output di --version se lavori da riga di comando), sistema operativo, tipo di installazione, log completo del task, descrizione del dataset e, se esiste, il report PDF. Rivolgiti alla community della tua linea: Discord di WebODM per la linea WebODM, forum community.opendronemap.org per la linea OpenDroneMap; per OpenDroneMap Desktop c'è anche il supporto incluso con l'acquisto. Con questi elementi le community rispondono in fretta: Community e supporto. In una configurazione ibrida (interfaccia di una linea, nodo dell'altra) riproduci prima il problema con componenti della stessa linea. Se manca un errore importante, segnalacelo dal form dei contatti.

Prossimi passi#

• Il task finisce ma il risultato ha buchi o deformazioni: Risultati scadenti: buchi, effetto ciotola, quote sbagliate.
• Repository, immagini e migrazioni tra le linee: Repository, immagini Docker e migrazioni.
• Ridurre tempi e memoria prima che il problema si ripresenti: Ottimizzare tempi e memoria.
• Dimensionare correttamente il computer: Requisiti hardware.