[Guide] Fix pgvecto.rs "shared_preload_libraries" error after Immich v3.0.1 upgrade

[minto3792]

Hey everyone! After upgrading to Immich v3.0.1, I ran into a persistent crash loop with the microservices worker. Took some digging to figure out what was going on, so I'm sharing the fix here to save others the headache.

---

The Problem

After upgrading, my microservices worker kept dying with this error:

PostgresError: pgvecto.rs: pgvecto.rs must be loaded via shared_preload_libraries.

The server would start, immediately fail the vector reindexing checks, kill the microservices worker, and take down the API with it. Infinite restart loop.

---

Root Cause

Immich v3.0.1 requires both vchord.so and vectors.so (pgvecto.rs) to be preloaded in PostgreSQL. If your shared_preload_libraries only loads one of them, any queries hitting the missing extension will fail.

This commonly happens if:

• You have a custom command in docker-compose that only references vchord.so
• You followed older migration guides that set up only one extension
• You have conflicting settings between postgresql.auto.conf and your docker-compose command

---

Background Context

If you're coming from an older Immich version, you may have previously migrated to vectorchord following the official guide:

👉 Migrating to VectorChord (Immich Docs)

That migration guide was created when Immich was transitioning from pgvector to vectorchord. However, Immich v3.0.1 now requires both extensions to coexist — vchord for its vector operations and pgvecto.rs for certain index types. If you only loaded one after following the older migration steps, that's likely why you're hitting this error now.

---

How to Diagnose

Run these commands to check your current setup:

# What's currently loaded?
docker exec -it immich_postgres psql -U postgres -c "SHOW shared_preload_libraries;"

# Any conflicting auto.conf?
docker exec -it immich_postgres cat /var/lib/postgresql/data/postgresql.auto.conf

# Does vectors.so exist in your image?
docker exec -it immich_postgres find / -name "vectors.so" 2>/dev/null | grep lib

# Which PostgreSQL image are you using?
docker inspect immich_postgres | grep -i "image.*immich"

If SHOW shared_preload_libraries returns only vchord.so but vectors.so exists in your container, you've found the issue.

---

The Fix

Step 1: Update docker-compose.yml

Modify your command to load both extensions:

database:
  container_name: immich_postgres
  image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
  environment:
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_USER: ${DB_USERNAME}
    POSTGRES_DB: ${DB_DATABASE_NAME}
    POSTGRES_INITDB_ARGS: '--data-checksums'
  volumes:
    - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
  command: >-
    postgres 
    -c shared_preload_libraries='vchord.so,vectors.so' 
    -c logging_collector=on 
    -c max_wal_size=2GB 
    -c shared_buffers=512MB 
    -c wal_compression=on
  shm_size: 128mb
  restart: always

Key change: shared_preload_libraries now includes both vchord.so AND vectors.so, separated by a comma.

Step 2: Clean up conflicting settings

If you previously ran ALTER SYSTEM commands, clear them out:

docker exec -it immich_postgres psql -U postgres -c "ALTER SYSTEM RESET shared_preload_libraries;"

Step 3: Restart services

# Restart PostgreSQL first
docker compose restart immich_postgres

# Verify both libraries are loaded
docker exec -it immich_postgres psql -U postgres -c "SHOW shared_preload_libraries;"
# Should output: vchord.so,vectors.so

# Verify extensions are present
docker exec -it immich_postgres psql -U postgres -d immich -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('vectors', 'vchord');"

# Restart Immich
docker compose restart immich_server immich_machine_learning

Step 4: Confirm it's working

Check your logs — you should see the microservices worker start cleanly:

docker compose logs -f immich_server | grep -i "microservices\|error\|warn"

No more "pgvecto.rs must be loaded" errors, and the vector reindexing checks should pass without warnings.

---

Verification Checklist

✅ SHOW shared_preload_libraries returns vchord.so,vectors.so
✅ No "must be loaded via shared_preload_libraries" errors in logs
✅ Microservices worker starts successfully
✅ Vector reindexing completes without warnings
✅ Immich web UI accessible

---

Why This Happens

The official migration guide helped many of us transition from pgvector to vectorchord in earlier versions. At that time, the guidance was to load vchord.so and remove references to vectors.so. Immich v3.0.1 changed this — it now uses both extensions for different purposes, so you need both loaded simultaneously. If you still have the old single-extension config from the migration, this upgrade will break until you update it.

---

Hope this helps someone avoid the headache! If you're still stuck, double-check that you're not overriding the command somewhere else (environment variables, separate config files, etc.) and that your PostgreSQL image actually has both extensions installed.

Cheers 🍻

[FredyatGitHub]

Thanks a lot! It worked perfectly for me.