immich-app/immich · critical

The extension version is , but Immich only supports …

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 extension's available version must satisfy the range required by this Immich release (getExtensionVersionRange, e.g. ^0.3.0 for VectorChord or >=0.5.5 <1 for pgvector). If the newest version available in the Postgres instance is outside that range, startup aborts with messages.outOfRange.

Solutions

  1. Upgrade (or downgrade) the extension to a version within the required range shown in the error, e.g. pull a matching ghcr.io/immich-app/postgres image tag.
  2. Upgrade Immich to a version whose extension range matches what your Postgres image provides.
  3. Verify with 'SELECT * FROM pg_available_extension_versions' that the required version is actually installable in the instance.

Example fix

# before
image: tensorchord/pgvecto-rs:pg15-v0.2.0
# after
image: ghcr.io/immich-app/postgres:15-vectorchord0.3.0
Defensive patterns

Strategy: try-catch

Validate before calling

const { rows } = await db.query("SELECT max(version) FROM pg_available_extension_versions WHERE name='vectorchord'");
if (!semver.satisfies(rows[0].max, '^0.3.0')) console.error('Extension version out of supported range');

Try / catch

try {
  await server.start();
} catch (e) {
  if (/only supports/.test(e.message)) {
    console.error('Align extension version with the range Immich requires:', e.message);
  } else throw e;
}

Prevention

When it happens

Trigger: Bootstrap where getAvailableExtension returns a version like 0.2.x or 0.4.x when Immich requires a different major/minor range — e.g. pgvector too old in a stock image, or VectorChord too new for the pinned Immich release.

Common situations: Upgrading the extension image ahead of Immich; running an old Postgres image after upgrading Immich; Debian packages shipping older pgvector.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/7af374b85b34c1ee. Report an issue: GitHub.

Appendix: 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 && eq(version, '0.0.0'))) {
        throw new Error(messages.nightlyVersion({ name, extension, version: '0.0.0' }));
      }

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

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

      if (installedVersion && gt(availableVersion, installedVersion)) {
        await this.updateExtension(extension, availableVersion);
      } else if (installedVersion && !satisfies(installedVersion, extensionRange)) {
        throw new Error(messages.outOfRange({ name, extension, version: installedVersion, range: extensionRange }));
      } else if (installedVersion && 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 e55ac299a4)