immich-app/immich · critical · Error

The ${name} extension version is ${version}, but Immich only

Error message

The ${name} extension version is ${version}, but Immich only supports ${range}.
    Please change ${name} to a compatible version in the Postgres instance.

What it means

The vector extension that Postgres makes available (default_version in pg_available_extensions) does not satisfy the semver range Immich requires for that extension. This guard runs before any CREATE EXTENSION, so it fails even when nothing is installed yet. It prevents Immich from activating an extension version known to be incompatible with its schema and operators.

Source

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

    }

    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 }));
      } else if (installedVersion && semver.lt(availableVersion, installedVersion)) {
        throw new Error(messages.invalidDowngrade({ name, extension, availableVersion, installedVersion }));
      }

      try {
        await this.databaseRepository.reindexVectorsIfNeeded([VectorIndex.Clip, VectorIndex.Face]);
      } catch (error) {
        this.logger.warn(

View on GitHub (pinned to 199723261c)

Solutions

Check Immich's required range via getExtensionVersionRange for your extension (see the supported versions table in docs) and install a version inside it.
Update the extension package in the Postgres container/image to a compatible release (e.g. upgrade pgvector to a supported tag).
If only a too-new version is available, downgrade the package to the highest version still inside extensionRange.
Restart Postgres then Immich so bootstrap re-runs the satisfies() check.

Example fix

# check available + required
-- SELECT name, default_version FROM pg_available_extensions WHERE name='vector';
# install a compatible pgvector release matching Immich's range
RUN apt-get install -y postgresql-16-pgvector=0.7.*

Defensive patterns

Strategy: validation

Validate before calling

import pg from 'pg';
import semver from 'semver';
const REQUIRED = '>=0.5.0'; // replace with Immich's getExtensionVersionRange for your version
const client = new pg.Client({ connectionString: process.env.DB_URL });
await client.connect();
const { rows } = await client.query(
  "SELECT name, default_version FROM pg_available_extensions WHERE name IN ('vector','vectors');"
);
for (const r of rows) {
  if (r.default_version && !semver.satisfies(semver.coerce(r.default_version)!, REQUIRED)) {
    throw new Error(`${r.name} ${r.default_version} does not satisfy ${REQUIRED}`);
  }
}

Type guard

import semver from 'semver';
const extensionInRange = (version: string | undefined, range: string) =>
  !!version && !!semver.coerce(version) && semver.satisfies(semver.coerce(version)!, range);

Try / catch

try {
  await app.start();
} catch (e) {
  if (/only supports/.test(String(e?.message))) {
    logger.fatal('Vector extension out of supported range - install a compatible version');
    process.exit(1);
  }
  throw e;
}

Prevention

Track Immich's documented supported extension versions per server release.
Update the extension package whenever you upgrade Immich.
Add a CI check that asserts the deployed image's extension satisfies the range.

When it happens

Trigger: On bootstrap, availableVersion is set and non-zero but !semver.satisfies(availableVersion, extensionRange). Example: pgvector 0.4.x available while Immich requires >=0.5.0, or a too-new pgvecto.rs that broke compatibility.

Common situations: Postgres image bundled with an older pgvector; pinned an extension version that has since fallen out of the supported range after an Immich upgrade; using a Linux distro package that ships an old pgvector.

Related errors

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