The integration of Immich into the Umbrel ecosystem has provided users with a powerful, self-hosted alternative to proprietary photo cloud services. However, due to its heavy reliance on machine learning (ML) models, high-performance database indexing, and intensive video transcoding, users frequently encounter stability issues. Whether you are experiencing a “Connection Refused” error, stagnant library processing, or total system hangs, these issues typically stem from resource exhaustion or container desynchronization within the Docker stack.
This guide provides a deep-dive into the technical architecture of the Umbrel Immich implementation and offers systematic solutions for the most common failure points.
What the Umbrel Immich Error Actually Means
When Immich fails on Umbrel, it is rarely a single “bug.” Instead, it is usually a failure of one of the five core microservices that comprise the Immich stack. On Umbrel, Immich runs as a collection of Docker containers:
- immich_server: The main API and web interface.
- immich_microservices: Handles background tasks like metadata extraction and transcoding.
- immich_machine_learning: Processes facial recognition and object detection.
- immich_postgres: The relational database storing all metadata.
- immich_redis: The key-value store used for job queuing.
A failure in “Umbrel Immich” usually means the immich_server cannot communicate with immich_postgres or immich_redis. If the UI loads but photos do not process, the bottleneck is typically in the machine_learning or microservices container.
Main Causes of Failure
Understanding the root cause is essential before executing commands. In the context of Umbrel, failures generally fall into three categories:
1. Out of Memory (OOM) Events
Immich is resource-heavy. The machine learning container, by default, attempts to load models into RAM. On a Raspberry Pi 4 or 5 with 4GB or 8GB of RAM, this can trigger the Linux OOM Killer, which terminates the most RAM-intensive process to save the OS—usually the Immich ML container or the Postgres database.
2. Database Corruption or Lock-wait Timeouts
If an Umbrel loses power unexpectedly, the Postgres write-ahead log (WAL) can become inconsistent. Furthermore, if the underlying storage (microSD or slow external HDD) cannot keep up with the IOPS (Input/Output Operations Per Second) required by Postgres, the application will timeout.
3. Docker Network Desynchronization
Umbrel’s middleware sometimes fails to correctly route traffic through its internal proxy to the Immich containers after an update. This results in the “Bad Gateway” or “Unable to connect” screens despite the containers showing as “Running.”
Step-by-Step Fix for Umbrel Immich
Follow these steps in order. Do not skip the diagnostic checks, as they determine which fix is required.
Step 1: Accessing the Umbrel CLI
To troubleshoot effectively, you must bypass the web UI. Use SSH to access your Umbrel:
ssh -t umbrel@umbrel.local
(Replace umbrel.local with your device’s IP address if necessary. The default password is your dashboard password.)
Step 2: Diagnostic Log Inspection
Navigate to the Umbrel directory and check the status of the Immich containers:
cd ~/umbrel
docker compose ps | grep immich
If any container shows Exit 137, it was killed due to lack of memory. If it shows Restarting, there is a configuration or database connection error. To see the specific error, run:
docker compose logs immich_server --tail=50
Look for strings like Connection refused or QueryTimeoutError.
Step 3: Forceful Container Reset
Sometimes the Umbrel UI fails to stop the containers properly. A hard reset of the Immich stack often clears stale locks:
~/umbrel/scripts/app stop immich
~/umbrel/scripts/app start immich
Step 4: Repairing the Postgres Database
If the logs show database system was not gracefully shut down, you may need to force a recovery. Umbrel stores app data in specific paths. Check the integrity of the Immich database volume:
docker exec -it immich_postgres vacuumdb -U postgres -a -v
Step 5: Disabling Machine Learning (For Low-RAM Systems)
If your Umbrel keeps crashing, the ML features are likely the culprit. You can limit the memory usage by editing the environment variables, though Umbrel’s wrapper makes this difficult. A common workaround is to restrict the types of jobs Immich runs via the “Job Settings” in the web UI immediately after a successful start. Set “Thumbnail Generation” and “Facial Recognition” to concurrent limits of 1 or 2.
When It’s a Hardware Limitation
Many “umbrel immich” issues are not software bugs but hardware bottlenecks.
SSD vs. MicroSD
Running Immich on a microSD card is the primary cause of UI lag. Immich generates thousands of small thumbnail files and performs constant database writes. MicroSD cards lack the random-access speeds required, leading to high “iowait” times which freeze the Umbrel dashboard. An external SSD (via USB 3.0) or an NVMe drive is mandatory for libraries exceeding 10GB.
RAM Constraints
- 4GB RAM: Insufficient for Immich + Bitcoin Node + Lightning. You must disable ML features.
- 8GB RAM: The “sweet spot” for Raspberry Pi users, but still requires cautious job concurrency settings.
- 16GB+ (Mini PC/x86): Recommended for users with 100k+ photos who want instantaneous facial recognition.
CPU Architecture
While Raspberry Pi 5 has improved significantly, x86-64 processors (Intel N100 or better) handle HEVC/H.265 video transcoding much more efficiently via Intel QuickSync. If your Umbrel crashes specifically when uploading videos, your CPU is likely hitting 100% utilization and overheating.
When Reinstalling is Necessary
If the immich_postgres logs show “PANIC” or “FATAL” errors regarding the data directory, and vacuumdb fails, the database schema may be corrupted beyond repair.
Warning: Reinstalling the app via the Umbrel App Store will delete the database metadata but should preserve your actual photo files if they are stored in the standard app-data directory. However, you will lose all facial recognition data and manual albums.
To perform a clean reinstall of the software layer without deleting photos:
- Back up the
~/umbrel/app-data/immich/librarydirectory to an external source. - Uninstall Immich from the Umbrel Dashboard.
- Restart the Umbrel.
- Reinstall Immich.
How to Prevent Future Failures
- Use a High-Quality Power Supply: Most Umbrel database issues are caused by “Under-voltage” events on Raspberry Pis, which lead to SSD disconnects.
- Sequential Uploading: Do not attempt to upload 50,000 photos at once from the mobile app. Upload in batches of 5,000 to allow the microservices to clear the queue.
- Monitor System Temp: Use
vcgencmd measure_tempvia SSH. If your Umbrel is running above 70°C, it will throttle the CPU, causing Immich timeouts. - Static IP: Ensure your Umbrel has a reserved IP in your router settings to prevent Docker network bridge errors.
FAQ
Why does my Umbrel Immich say “Connecting…” indefinitely?
This is usually a DNS or proxy issue. If you are accessing via Tailscale, ensure the Tailscale exit node is not interfering with local IP resolution. Clear your browser cache or try the local IP instead of umbrel.local.
Can I move my Immich library to an external hard drive?
Umbrel by default uses the primary drive connected during setup. To move the library specifically, you would need to modify the docker-compose.yml in ~/umbrel/app-data/immich/, which is not recommended as Umbrel updates will overwrite these changes.
How do I update Immich on Umbrel?
Updates are handled through the Umbrel App Store. If an update hangs, SSH into the box and run ~/umbrel/scripts/update/update --app immich.
Does Immich on Umbrel support hardware acceleration?
On Raspberry Pi, it uses limited OpenMAX acceleration. On x86 Mini PCs, Umbrel’s Docker setup typically does not pass through the GPU drivers by default, meaning transcoding is CPU-bound.
Conclusion
Resolving issues with umbrel immich requires a methodical approach to resource management. Because Immich is the most demanding application in the Umbrel App Store, it serves as a “stress test” for your hardware. By monitoring Docker logs, ensuring high-speed SSD connectivity, and managing machine learning concurrency, you can maintain a stable and private photo cloud. If instability persists, consider migrating your Umbrel instance from a Raspberry Pi to a dedicated x86 Mini PC.
Internal Linking Suggestions:
