immich-app/immich · critical · Error

The ${name} extension is not available in this Postgres inst

Error message

The ${name} extension is not available in this Postgres instance.
    If using a container image, ensure the image has the extension installed.

What it means

Immich requires a vector similarity search extension (pgvector 'vector' or pgvecto.rs 'vectors', a.k.a. Chord) to be present in the Postgres instance before it can start. On bootstrap the DatabaseService queries pg_extension/pg_available_extensions for VECTOR_EXTENSIONS; if the configured extension has no availableVersion, startup aborts with this message. It is a hard precondition for running the server because vector indexes back CLIP and face recognition search.

Source

Thrown at server/src/services/database.service.ts:75

  async onBootstrap() {
    const version = await this.databaseRepository.getPostgresVersion();
    const current = semver.coerce(version);
    const postgresRange = this.databaseRepository.getPostgresVersionRange();
    if (!current || !semver.satisfies(current, postgresRange)) {
      throw new Error(
        `Invalid PostgreSQL version. Found ${version}, but needed ${postgresRange}. Please use a supported version.`,
      );
    }

    await this.databaseRepository.withLock(DatabaseLock.Migrations, async () => {
      const extension = await this.databaseRepository.getVectorExtension();
      const name = EXTENSION_NAMES[extension];
      const extensionRange = this.databaseRepository.getExtensionVersionRange(extension);

      const extensionVersions = await this.databaseRepository.getExtensionVersions(VECTOR_EXTENSIONS);
      const { installedVersion, availableVersion } = extensionVersions.find((v) => v.name === extension) ?? {};
      if (!availableVersion) {
        throw new Error(messages.notInstalled(name));
      }

      if ([availableVersion, installedVersion].some((version) => version && semver.eq(version, '0.0.0'))) {
        throw new Error(messages.nightlyVersion({ name, extension, version: '0.0.0' }));
      }

      if (!semver.satisfies(availableVersion, extensionRange)) {
        throw new Error(messages.outOfRange({ name, extension, version: availableVersion, range: extensionRange }));
      }

      if (!installedVersion) {
        await this.createExtension(extension);
      }

      if (installedVersion && semver.gt(availableVersion, installedVersion)) {
        await this.updateExtension(extension, availableVersion);
      } else if (installedVersion && !semver.satisfies(installedVersion, extensionRange)) {
        throw new Error(messages.outOfRange({ name, extension, version: installedVersion, range: extensionRange }));

View on GitHub (pinned to 199723261c)

Solutions

  1. Switch to the Immich-bundled or pgvector/pgvecto.rs Postgres image (tensorchord/pgvecto.rs or pgvector/pgvector) matching the version in docker/docker-compose.yml.
  2. Inside the running Postgres container run 'SELECT name, default_version FROM pg_available_extensions WHERE name IN ('vector','vectors');' to confirm the extension package exists; if absent, install the package for that PG major version.
  3. Verify the IMMICH/DB vector extension env var matches an extension that is actually packaged (default is 'vectors' for the bundled image); change it to 'vector' only if you installed pgvector.
  4. Restart the Immich server after the Postgres image/extension is fixed so the bootstrap check re-runs.

Example fix

# before: plain postgres image
#  image: postgres:16
# after: image with the vector extension
image: tensorchord/pgvectors:pg16
# then in psql confirm:
-- SELECT * FROM pg_available_extensions WHERE name = 'vectors';
Defensive patterns

Strategy: validation

Validate before calling

// before starting Immich, verify the extension package is present in Postgres
import pg from 'pg';
const client = new pg.Client({ connectionString: process.env.DB_URL });
await client.connect();
const res = await client.query(
  "SELECT name FROM pg_available_extensions WHERE name IN ('vector','vectors');"
);
if (res.rowCount === 0) {
  throw new Error('No vector extension available in Postgres - install pgvector/pgvecto.rs first');
}

Type guard

const hasVectorExtension = (rows: { name: string }[]) =>
  rows.some((r) => r.name === 'vector' || r.name === 'vectors');

Try / catch

try {
  await app.start(); // triggers DatabaseService.onBootstrap
} catch (e) {
  if (/extension is not available/.test(String(e?.message))) {
    logger.fatal('Vector extension missing - fix the Postgres image before retrying');
    process.exit(1);
  }
  throw e;
}

Prevention

When it happens

Trigger: AppBootstrap event fires, DatabaseService.onBootstrap runs, getVectorExtension returns the configured extension (e.g. 'vectors'), getExtensionVersions returns no row with a non-null availableVersion for it. Triggered: fresh DB without the extension, a custom/minimal Postgres image, or VECTOR_EXTENSIONS env var pointing at an extension the image lacks.

Common situations: Using a plain postgres Docker image instead of the pgvector/pgvecto.rs image; mis-setting the vector extension env var; Postgres upgrade that dropped the extension; RDS/Cloud SQL without the vector extension package installed.

Related errors

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/9ab56d0829ae995c. Report an issue: GitHub.