I started running Immich last spring to get off Google Photos. It’s a solid self-hosted photo backup tool with real AI features—facial recognition, object detection, smart search that actually works. But the first week was rough. The container wouldn’t start. Memory filled up. The database locked. Let me walk through what broke and how I fixed it, because these errors are common and the error messages are terrible.
PostgreSQL Connection Refused on Startup
Day one. Pulled the Docker compose file from the Immich docs, ran it, watched the server container fail immediately.
immich-server | Error: connect ECONNREFUSED 127.0.0.1:5432The server couldn’t talk to PostgreSQL. Not because the database was broken—it was still starting up. Docker Compose runs containers in parallel by default. The Immich server gets to port 5432 before postgres is actually accepting connections.
The fix is simple: add depends_on with a condition. Modern Docker Compose syntax:
services:
immich-server:
depends_on:
immich-postgres:
condition: service_healthy
# rest of config
immich-postgres:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5That healthcheck tells Compose “don’t start the server until postgres actually responds to pg_isready.” This added maybe 15 seconds to startup but it was reliable after that. Most docker-compose files online skip the healthcheck. Don’t skip it.
Out of Memory: Machine Learning Models Loading
Second week. Everything ran fine for two days. Then the container killed itself. dmesg showed OOM (out of memory). I had 4GB allocated to the VM.
Immich downloads and loads ML models the first time you use facial recognition or object detection. Each model takes 200MB to 800MB. If you enable face detection, object tagging, and CLIP (the natural language search), that’s roughly 2GB of RAM just sitting there after startup.
I checked what was loading:
docker exec immich-server du -sh /usr/src/app/node_modules/.immich/1.4GB. The models cache lives in there. The server was trying to load them all at once during first use.
Two options. Option one: disable features you don’t use. In the Immich admin panel under Machine Learning settings, I turned off video object detection and kept just face detection and CLIP. That cut the footprint to about 900MB.
Option two: allocate more RAM. I increased the container memory limit to 6GB and gave the VM 8GB total. It’s not elegant but it works. On a Ryzen 5 homelab box, 8GB was reasonable.
services:
immich-server:
mem_limit: 6g
memswap_limit: 6gIf you’re running this on something smaller (NAS, RPi), you’ll want to be aggressive about disabling ML features. CLIP and face detection are the heavy hitters. Disable them if you don’t need them.
Database Locked: Concurrent Backup and Indexing
Month two. I’d set up automatic photo backup from my phone. One morning I tried to search for something and got this:
database is lockedAnd then the search timed out. The issue: Immich was building its search index while the mobile app was uploading photos. SQLite would have handled this fine, but Immich uses PostgreSQL and I'd somehow misconfigured the connection pool. Connections were exhausted.
Check your docker-compose for the database connection parameters. Look for DB_POOL_SIZE and related settings. Mine looked like this:
The gear I run for this
Hardware from my own homelab, relevant to this guide — direct Amazon links.
Synology DS224+ 2-Bay NASTurnkey 2-bay NAS for photos, backups, and self-hosted apps. Runs Docker, Plex, and Immich out of the box.~AED 1,400Raspberry Pi 5 (8GB)The ultimate homelab starter. Run Pi-hole, Home Assistant, lightweight AI, and Docker containers.~AED 370Google Coral USB AcceleratorPlug-and-play Edge TPU for local AI inference. Perfect for Frigate NVR, object detection, and lightweight ML models.~AED 350Affiliate links — I earn a small commission at no extra cost to you. Browse my full homelab store →
environment: DB_POOL_SIZE: "25" DB_POOL_IDLE_TIMEOUT: "30000"That's actually the default and should be fine. My real problem was different: I had two instances of the server running (I'd been testing a scale-out setup). Two instances meant 50 concurrent connections fighting over a database that wasn't tuned for it.
I killed the second instance. One immich-server is enough unless you're doing something unusual. The lock errors stopped.
If you're hitting database locks without running multiple servers, increase the PostgreSQL max_connections setting. SSH into the container and edit it:
docker exec -it immich-postgres psql -U postgres # ALTER SYSTEM SET max_connections = 200; # SELECT pg_reload_conf();Then restart. Default is 100. Most homelabs are fine with 100 unless they're doing concurrent transcoding or running other services on the same database.
Microservices Crashing: Missing IMMICH_API_URL
The microservices containers (ml, typesense) kept exiting. The logs were useless at first glance:
immich-ml | [2024-01-15 10:22:33] ERROR - Failed to connectMicroservices need to know how to reach the main API server. If you're using a reverse proxy or accessing Immich through a hostname instead of localhost, you need to set IMMICH_API_URL explicitly in your compose file. Mine was:
environment: IMMICH_API_URL: http://immich-server:3001Sounds obvious but if you're accessing the web UI through a reverse proxy (say, https://photos.example.com) the microservices still need to talk to the server at its internal Docker network address, not through your public domain.
I was running Caddy in front of Immich and forgot to set this. The microservices tried to hit the external URL, which Caddy didn't know how to route back into Docker, and they failed. Setting the internal address fixed it.
Uploads Failing: Insufficient Disk Space Detection
Third month in. Uploads from the mobile app started failing with a cryptic error. Browser showed "Insufficient storage." But I had 2TB free on the disk.
Immich checks available disk space before accepting uploads. If it can't write a temporary file to the upload directory, it rejects the request. My upload path was set to a partition that wasn't the same one where my photos actually lived.
Check your docker-compose UPLOAD_LOCATION variable:
environment: UPLOAD_LOCATION: /photosAnd your volume mount:
volumes: - /mnt/storage/photos:/photosMake sure that mount point has free space. I'd mounted it to /mnt/temp which had 50GB but was filling up with system logs. Moving the mount to /mnt/storage (which had 2TB free) resolved it in seconds.
If you can't move the mount, at least increase the disk allocation and enable log rotation on the container. Immich logs verbosely.
The Experience: What I'd Do Differently
Most of these errors came from gaps between the official documentation and reality. The docs are good but they don't cover the edge cases—what happens when you run out of RAM, what the microservices actually need to function, how PostgreSQL behaves under load.
If I were starting over, I'd do this: allocate 8GB RAM minimum, enable the PostgreSQL healthcheck, and disable ML features I don't use before the first upload batch. That's it. You'll avoid 80% of the early friction.
Immich itself is solid. It's not a Google Photos clone (it doesn't pretend to be). The AI search works. Backup is reliable. The only gotcha is that self-hosting requires you to make decisions Google makes for you—how much memory to give the ML models, whether you want face detection eating CPU. That's a feature, not a bug. But it's also why the first week can feel broken when it's just misconfigured.
FAQ
Can Immich run on a Raspberry Pi?
Technically yes, but it's slow. A Pi4 with 4GB RAM can run the server, but ML features (facial recognition, object detection) will take minutes per photo. If you're just doing backup and basic search, Pi4 with 8GB is possible. Most people moving serious photo libraries should use at least a Ryzen 5 or Intel i5 with 8GB+ RAM.
Does Immich need PostgreSQL or can I use SQLite?
Immich requires PostgreSQL. No SQLite option. The official docker-compose includes a PostgreSQL container, so you don't need to manage it separately, but it must be PostgreSQL.
How much disk space does Immich need for 100,000 photos?
Depends on original file size. Immich stores originals plus generates thumbnails and preview images. Budget roughly 1.5x to 2x the size of your photo library. If your raw photos are 500GB, expect 750GB-1TB total disk usage after Immich processes them.
Does Immich require internet connection?
No. Everything runs locally. Facial recognition, object detection, and natural language search all happen on your own hardware. You don't need internet after the initial setup.
Can I access Immich remotely without a VPN?
Yes, if you put it behind a reverse proxy (Caddy, Nginx, Traefik) and expose it safely. You'll want HTTPS and possibly authentication. A reverse proxy isn't required but it's strongly recommended for security. VPN access is simpler and safer for personal use.
Explore Immich in our AI Homelab Toolkit.