WebODM Troubleshooting Guide | Fix Processing Issues
introduction
WebODM is a powerful open-source platform for drone image processing, offering flexibility and control unmatched by most commercial alternatives. However, being open source, WebODM sometimes requires manual troubleshooting, especially when dealing with Docker containers, memory issues, and crashes during processing.
This guide focuses on practical WebODM troubleshooting methods, primarily for Mac users, but the same logic largely applies to Windows users as well. If you’ve installed and setup WebODM already, this troubleshooting guide will help you efficiently diagnose and fix most common problems.
Basic WebODM Commands
When managing WebODM through the terminal, these commands will become your best friends:
# To start WebODM
./webodm.sh start
# To stop WebODM:
./webodm.sh stop
# To restart WebODM with fresh node setup (useful for troubleshooting):
./webodm.sh restart --default-nodes
These basic commands allow you to control your WebODM instance and are often the first steps during error resolution.
Terminal-Level Troubleshooting
If WebODM becomes unresponsive or processing stalls, first manage it through the terminal:
Step 1: Stop Current Processes
Use Ctrl + C to terminate any running processes cleanly. If the terminal already shows WebODM has stopped, proceed to the next step.
Step 2: Safe Restart
Attempt to stop and start the instance:
./webodm.sh stop
./webodm.sh start
If WebODM fails to restart or you cannot load the Localhost (http://localhost:8000), proceed to restart the nodes:
./webodm.sh restart --default-nodes
If none of these work, you’ll need to dive deeper into Docker troubleshooting.
Docker Troubleshooting
WebODM heavily relies on Docker. Problems with storage, RAM, swap memory, or Docker containers are a common root cause of failures.
Check Your Storage and Resources
Ensure your hard drive has ample free space. Processing tasks often require 6x or more the input image file size.
Set RAM and Swap memory allocations to maximum in Docker’s settings.
Use WebODM’s Diagnostics Panel to anticipate memory-related issues before launching large tasks.
Example: A 15GB set of images might require 90GB+ of free disk space during processing.
Levels of WebODM Cleanup for Troubleshooting
Depending on the severity of the issue, different levels of resource cleanup are recommended:
Salvaging Completed Tasks – Level 1
If your WebODM instance crashes but you have completed tasks you haven’t downloaded yet:
Delete the current Docker container.
Delete all volumes except
webodm_appmediaandwebodm_dbdata.
- Start WebODM using:
./webodm.sh start
Once WebODM UI loads, download all completed tasks immediately via All Assets option.
This method preserves old processed outputs while freeing up basic system resources.
Full Resource Cleanup – Level 2
When preparing for heavy new processing tasks:
Delete the container and all volumes, including
webodm_appmediaandwebodm_dbdata.Start WebODM freshly:
./webodm.sh start
If login issues occur, manually navigate to:
and continue using saved credentials or re-register.
This ensures maximum free space and clears stale task data.
Image Delete and Full Reset – Level 3
If WebODM continues malfunctioning even after node resets:
Delete Docker containers AND images.
Restart WebODM using the terminal, allowing it to pull a fresh image from GitHub:
You can choose to salvage old tasks or start completely clean based on whether volumes are kept.
This process resolves deeper software conflicts, but is slower because it re-downloads WebODM.
Other General Troubleshooting Tips
If Docker itself freezes, force quit Docker and restart your computer.
WebODM Lightning Node cloud processing is sensitive to unstable internet. Prefer using it with a strong connection or fallback to local processing.
Multispectral (MS) image processing sometimes fails over cloud processing (lightning) due to band mismatches caused by upload glitches due to choppy internet. Always verify band counts before upload as well.
Consistent internet is critical even if you are using the lightning node locally (via your instance).
Best Practices for Reliable WebODM Usage
Run only one task at a time.
Download completed tasks immediately to avoid accidental loss.
Clear resources (Level 2 cleanup) frequently before starting large tasks.
Separate RGB and Multispectral image processing into distinct tasks.
For RGB images:
Use Default processing mode.
Enable DTM (Digital Terrain Model) if needed.
Set Orthophoto resolution to 2cm for better quality.
For Multispectral images:
Select only the Multispectral mode — no additional edits needed.
Prefer local processing and then upload final outputs to WebODM cloud if remote access is needed.
Download “All Assets” instead of “Backup” (with resized images) to minimize file size.
Maintaining a clean, resource-optimized local WebODM instance ensures faster, more reliable processing, and minimizes frustration.
Conclusion
Troubleshooting WebODM can seem daunting at first, but with a structured approach — controlling instances, managing Docker resources, and maintaining best practices — you can confidently handle almost any processing issue.
If persistent problems continue, or you want expert help setting up a streamlined drone data workflow, feel free to contact Future Thota. We specialize in drone mapping, processing optimization, and geospatial data solutions tailored to agricultural and plantation sectors.
