Cómo arreglar No vector extension found al actualizar Immich a v3

El error No vector extension found. Available extensions: vchord, vector significa que Immich v3 arranca sobre una base de datos que solo tiene pgvecto.rs, y se arregla cambiando la imagen de Postgres, no el servidor de Immich. La versión 3.0.0, publicada el 2 de julio de 2026, retiró pgvecto.rs; si tu docker-compose.yml aún usa tensorchord/pgvecto-rs, el servidor entra en un bucle de reinicios. Esta guía reproduce el error, los otros dos fallos que vas a ver al intentar arreglarlo a ciegas y la migración a VectorChord que conserva la búsqueda inteligente y las caras. Lo probé el 18 de octubre de 2026 en Linux arm64 con Docker 29.5.2, Compose v2.40.3 e Immich v1.132.3, v2.7.5 y v3.3.3. Tienes la versión en inglés de esta guía.

Puntos clave

• El error sale cuando el contenedor de Postgres no ofrece ni vchord ni vector; la lista del mensaje es lo que Immich admite, no lo que tienes instalado.
• La etiqueta release que traía el .env de ejemplo antiguo apunta hoy a v3.3.5 (en mi prueba, a v3.3.3), así que un docker compose pull te lleva a la versión 3 sin avisar.
• El arreglo es la imagen ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0, que trae las dos extensiones y permite la conversión.
• En mi prueba, las 15 fotos, los 15 vectores de búsqueda, las 2 caras y la persona con nombre sobrevivieron a las dos rutas que funcionan.
• Si saltas directamente a v3, la extensión antigua vectors se queda instalada: bórrala con DROP EXTENSION vectors; antes de quitar la imagen doble.

¿Qué significa Error: No vector extension found en Immich v3?

Significa que Immich v3 buscó en Postgres una extensión vectorial que sabe usar y no encontró ninguna. Para reproducirlo monté Immich v1.132.3 con su compose oficial de entonces, la imagen tensorchord/pgvecto-rs:pg14-v0.2.0, y le cambié solo IMMICH_VERSION a v3.3.3. El servidor se reinicia cada pocos segundos con este registro:

Initializing Immich v3.3.3
Detected CPU Cores: 18
Starting api worker
Starting microservices worker
Error: No vector extension found. Available extensions: vchord, vector
    at getVectorExtension (file:///usr/src/app/server/dist/
    repositories/database.repository.js:46:15)
microservices worker error: Error: No vector extension found.
Available extensions: vchord, vector
microservices worker exited with code 1
Killing api process

He partido dos líneas para que quepan; en tu terminal salen enteras. La interfaz web no responde mientras dura el bucle, y la aplicación móvil no puede conectar con el servidor. Es lo que describe la incidencia 29453 de Immich^[1], abierta el mismo 2 de julio.

Por qué la lista del mensaje despista

La parte Available extensions: vchord, vector no describe tu base de datos. En el código fuente de v3.3.3^[2], Immich consulta pg_available_extensions buscando vchord (VectorChord) y vector (pgvector), y si no encuentra ninguna imprime la constante con las dos que admite. En mi base de datos antigua, esa consulta solo devolvía vectors 0.2.0, que es el nombre interno de pgvecto.rs:

SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('vectors', 'vchord', 'vector');
-- vectors | 0.2.0 | 0.2.0

Qué versiones de Immich disparan el error

El error aparece al pasar a cualquier v3 desde una instalación que nunca migró a VectorChord. Eso incluye Immich anterior a v1.133.0 y cualquier versión posterior que siguió con la imagen antigua. Estas son las fechas que importan:

Las notas de la versión v3.0.0 de Immich^[3] lo avisan en un recuadro. Dicen: "v3.0.0 drops support for pgvecto.rs. If you run Immich before v1.133.0 and haven’t done the migration step yet, see the migration guide here." El problema es que el example.env de v1.132.3 traía IMMICH_VERSION=release. Cualquier actualización automática, como la que hace Watchtower con tus contenedores, te dejó en v3 sin pasar por esas notas.

Los otros dos errores que salen al intentar arreglarlo

Hay dos atajos que parecen razonables y fallan con mensajes distintos. Los reproduje sobre una copia de la misma base de datos para que reconozcas cada uno.

El primero es forzar la extensión antigua con la variable DB_VECTOR_EXTENSION=pgvecto.rs, que funcionaba en la rama 1. Immich v3 valida las variables al arrancar y para en seco:

Error: Invalid environment variables:
  - [DB_VECTOR_EXTENSION] Invalid option: expected one of
    "pgvector"|"vectorchord"

El anuncio de migración a v3^[4] lo confirma: "Using DB_VECTOR_EXTENSION=pgvecto.rs now throws an error." Quita la variable; con la imagen correcta Immich detecta la extensión solo.

El segundo es saltar a la imagen ghcr.io/immich-app/postgres:14-vectorchord0.4.3, la que no lleva pgvecto.rs. Immich crea VectorChord, pero las columnas de vectores siguen siendo del tipo de pgvecto.rs y Postgres no encuentra su biblioteca:

LOG [Microservices:DatabaseRepository] Creating VectorChord extension
PostgresError: could not access file "$libdir/vectors":
No such file or directory
WARN [Microservices:DatabaseService] Could not run vector reindexing
checks.

Este fallo no rompe nada: al cambiar después a la imagen doble, Immich v3.3.3 terminó la migración y conservó todos los datos.

Cómo arreglar el error: la imagen de Postgres con VectorChord y pgvecto.rs

El arreglo es cambiar el servicio database por la imagen que trae a la vez VectorChord y pgvecto.rs, para que Immich pueda leer los vectores antiguos y reescribirlos en el formato nuevo. Es la misma imagen que usa hoy el compose oficial de v3.3.3.

Paso 1: haz una copia de la base de datos

Haz la copia con la imagen antigua todavía en marcha, porque es la única que puede leer las columnas de pgvecto.rs. Es el comando de la guía de copias de seguridad de Immich^[5]; en mi laboratorio el contenedor llevaba otro prefijo:

docker compose stop immich-server
docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > immich-antes-de-v3.sql.gz

Mi copia ocupó 15 MB comprimida con solo 15 fotos, porque la base de datos incluye la tabla de lugares para la geolocalización inversa. Si tu biblioteca es grande, para también los contenedores y copia el directorio DB_DATA_LOCATION entero.

Paso 2: cambia el servicio database del compose

Sustituye la imagen y borra las líneas command: y healthcheck: antiguas, porque la imagen nueva ya trae su configuración de Postgres. Este es el bloque que dejé, igual al del compose oficial de v3.3.3 salvo el resumen sha256 de la imagen:

  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'
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always

Si el .env contiene DB_VECTOR_EXTENSION, bórrala. Descomenta DB_STORAGE_TYPE solo si la base de datos vive en un disco duro mecánico.

Paso 3: arranca primero la rama 2 y después la 3

La ruta más limpia es pasar por v2.7.5 con la imagen doble, porque la rama 2 todavía sabe borrar pgvecto.rs cuando termina. Pon IMMICH_VERSION=v2 en el .env y arranca:

docker compose pull
docker compose up -d
docker compose logs -f immich-server

En el registro deberías ver esta secuencia, seguida de 67 migraciones en mi caso:

LOG [Microservices:DatabaseRepository] Creating VectorChord extension
LOG [Microservices:DatabaseRepository] Reindexing clip_index
(This may take a while, do not restart)
LOG [Microservices:DatabaseRepository] Reindexing face_index
(This may take a while, do not restart)
LOG [Microservices:DatabaseRepository] Reindexed clip_index
LOG [Microservices:DatabaseRepository] Reindexed face_index
LOG [Microservices:DatabaseRepository] Dropping pgvecto.rs extension

Con 15 fotos la reindexación fue inmediata; la documentación de Immich advierte que con más de 100 000 elementos o un servidor modesto puede tardar minutos, y que no debes reiniciar mientras tanto. Cuando Immich v2.7.5 responda, cambia a IMMICH_VERSION=v3 y la imagen a ghcr.io/immich-app/postgres:14-vectorchord0.4.3, y repite pull y up -d. En mi prueba v3.3.3 aplicó 32 migraciones más y arrancó sin avisos.

Atajo: directo a v3 con la imagen doble

También puedes saltar de v1.132.3 a v3.3.3 sin pasar por la rama 2, siempre que uses la imagen doble del paso 2. Lo probé: aplicó 99 migraciones de golpe y la búsqueda y las caras funcionaron. La diferencia es que v3 ya no conoce pgvecto.rs y no lo desinstala, así que la extensión vectors 0.2.0 sigue registrada y tus copias con pg_dump incluyen CREATE EXTENSION IF NOT EXISTS vectors. Bórrala cuando Immich haya arrancado:

docker exec immich_postgres psql -U postgres -d immich \
  -c "DROP EXTENSION vectors;"

Después ya puedes pasar a la imagen 14-vectorchord0.4.3 sin pgvecto.rs. El primer arranque en v3 me dio además un aviso de schema drift por un índice de geodata_places, que desapareció al reiniciar el servidor: era la importación de lugares, que aún no había terminado.

Cómo comprobar que la búsqueda y las caras siguen ahí

La comprobación tiene dos partes: que Postgres usa VectorChord y que los datos de aprendizaje automático (ML) siguen en sus tablas. Ejecuté estas consultas tras la ruta recomendada:

docker exec immich_postgres psql -U postgres -d immich -c \
  "SELECT extname, extversion FROM pg_extension
   WHERE extname IN ('vectors', 'vchord', 'vector');"
docker exec immich_postgres psql -U postgres -d immich -c \
  "SELECT indexname FROM pg_indexes WHERE indexdef LIKE '%vchordrq%';"
docker exec immich_postgres psql -U postgres -d immich -c \
  "SELECT (SELECT count(*) FROM smart_search) AS clip,
          (SELECT count(*) FROM face_search) AS faces,
          (SELECT count(*) FROM person) AS people;"

La primera devolvió vector 0.8.1 y vchord 0.4.3, sin rastro de vectors. La segunda listó clip_index y face_index, los dos con el método vchordrq de VectorChord. La tercera dio 15, 2 y 1: los mismos 15 vectores de búsqueda, 2 caras y 1 persona que tenía en v1.132.3.

Los vectores no solo están: siguen respondiendo igual. Antes y después de la migración, la búsqueda inteligente de "pink flowers" devolvió el ciclamen, la Orychophragmus y la Polemonium en el mismo orden, y la persona conservó el nombre "Retrato de prueba". Las fotos de prueba fueron 9 de naturaleza y 2 retratos del repositorio de dominio público immich-app/test-assets^[6], más 4 figuras geométricas generadas. El contenedor de ML tenía un límite de 6 GB.

Si usas PostgreSQL 15 o 16 o una base de datos externa

La imagen debe conservar la versión mayor de Postgres de tu directorio de datos, porque cambiar de 14 a 16 no se arregla con una etiqueta. La guía de migración a VectorChord^[7] explica el cambio de nombre: pg16-v0.3.0 pasa a 16-vectorchord0.3.0-pgvectors0.3.0. Comprobé que estas etiquetas existen en el registro de GitHub el 18 de octubre de 2026:

Solo probé la fila de Postgres 14, que es la del compose oficial. Si tu Postgres es un servidor compartido o un paquete de tu distribución, instala VectorChord desde su repositorio oficial^[8] antes de actualizar. El propio repositorio de pgvecto.rs^[9] recomienda migrar a VectorChord. Si quieres entender qué guardan esas columnas, el artículo sobre búsqueda semántica con pgvector explica los vectores e índices que Immich usa por debajo.

Preguntas frecuentes

¿Pierdo las caras y la búsqueda inteligente al migrar a VectorChord?

No, si usas la imagen doble. Immich convierte las columnas existentes y reconstruye los índices sin volver a pasar las fotos por el ML: mis 15 vectores, 2 caras y la persona con nombre siguieron igual en v3.3.3.

¿Puedo volver a v1.132 si algo sale mal?

No sobre la misma base de datos. La documentación de Immich dice que tras pasar a VectorChord no debes bajar de v1.133.0, así que la vuelta atrás es restaurar la copia del paso 1 con la imagen antigua.

¿Por qué me pasó sin haber cambiado nada?

Porque tu .env tenía IMMICH_VERSION=release, que desde el 2 de julio de 2026 apunta a la rama 3. Fija una versión mayor (v2 o v3) para que una actualización automática no cruce de rama; la guía para instalar Immich con Docker explica esa variable.

Conclusión

No vector extension found no es un fallo de Immich v3, sino la señal de que tu Postgres sigue en pgvecto.rs. Haz una copia con la imagen antigua, cambia a 14-vectorchord0.4.3-pgvectors0.2.0, pasa por v2.7.5 si quieres que la extensión antigua se borre sola y termina en v3 con la imagen sin pgvecto.rs. Después, comprueba con las tres consultas que vchord está instalada y que los recuentos de vectores y caras coinciden con los de antes.

Fuentes: [1] Immich, notas de la versión v3.0.0^[3], [2] Immich, notas de la versión v1.133.0^[10], [3] Immich, migración a VectorChord^[7], [4] Immich, anuncio de la migración a v3^[4], [5] Immich, incidencia 29453^[1], [6] Immich, database.repository.ts en v3.3.3^[2], [7] Immich, copias de seguridad y restauración^[5], [8] TensorChord, VectorChord^[8], [9] TensorChord, pgvecto.rs^[9], [10] Immich, fotos de prueba de dominio público^[6].

Fuentes

1. incidencia 29453 de Immich
2. código fuente de v3.3.3
3. versión v3.0.0 de Immich
4. anuncio de migración a v3
5. guía de copias de seguridad de Immich
6. immich-app/test-assets
7. guía de migración a VectorChord
8. repositorio oficial
9. repositorio de pgvecto.rs
10. Immich, notas de la versión v1.133.0