Skip to content

2025

  • 1 min read

Breaking Change in v1.137: Upgrade Required for Older Versions

Immich v1.137.0 introduces a breaking change affecting users on versions older than v1.132.0 (released May 9, 2025). If you have automatic updates enabled (default), no action is required. However, the few users running older versions must manually upgrade to an intermediate version first.

Required Action

If running a version older than v1.132.0:

  1. Upgrade to v1.136.0 first: 
    sudo snap refresh immich-distribution --revision=218
  2. Allow Immich to start successfully
  3. Then upgrade to v1.137+ normally

Check your version: snap list immich-distribution

Why This Change?

Immich removed TypeORM (#20366) requiring database schema upgrades that must be completed on versions v1.132.0-v1.136.0 before upgrading to v1.137+.

Resources

Important Notifications & Backup database

New Notification System

Immich recently introduced a notification system and an API to send these notifications. I'm going to use this to inform you of important information in the future, and this is the first time you'll see a notification like this. All notifications will have a blog post like this one that contains additional information.

Immich has moved on from pgvecto.rs to VectorChord. That's a new vector extension to Postgres that is replacing it. At the moment Immich supports both but the old one will be deprecated in a future release.

Migration from pgvecto.rs to VectorChord should be automatic and safe, but there's always a risk. I have intentionally waited for about two months to make sure that code stabilized before pushing out this release, but to be on the safe side, I recommend highly that you make sure you have working backup.

There are two backup systems in Immich Distribution. The one provided by us and the one provided by the upstream Immich project. Please enable at least one of these backup options so it's possible to restore your installation if anything breaks.

You will find backups for Immich Distribution in /var/snap/immich-distribution/common/backups/ and you will find backups made by the builtin feature in Immich in /var/snap/immich-distribution/common/upload/backups/. You can also run the following command to list all backups: immich-distribution.backup -l.

As usual, I will always test everything to make sure this is a smooth, automatic zero care upgrade.

  • 1 min read

Automatic API Key for System Administration

Starting with revision 213, Immich Distribution automatically creates an internal API key for system administration tasks. This change has been in beta and is now released to stable.

What's New

The manager service automatically creates an API key named immich-distribution for the first admin user. This key is used exclusively for internal operations and enables the system to use official Immich APIs instead of direct database access for automated tasks.

What You Need to Know

  • No action required - The key is created and managed automatically
  • Internal use only - Not accessible to users, only for system operations
  • Maintenance schedule - Checked and recreated if needed twice daily (06:00 and 18:00)

This change improves reliability and follows best practices by using official APIs over custom solutions for internal functionality, internal scripts, and internal processes.

We have also extended the immich-admin CLI command with an extension to allow us to create this API key from inside the snap package. For more information about this extension, see the Immich Admin Extensions documentation.

If you notice any unexpected behavior, please report it on the GitHub repository.

  • 2 min read

Stuck at v1.133.1

If you find yourself stuck at version 1.133.1 with one of the following error messages, please continue reading.

error: cannot perform the following tasks:
- Run pre-refresh hook of "immich-distribution" snap if present (run hook "pre-refresh": 
-----
/snap/immich-distribution/195/snap/hooks/pre-refresh: line 9: /snap/immich-distribution/195/backup: No such file or directory
Failed to create and validate database backup during pre-refresh.
-----)

error: cannot perform the following tasks:
- Run pre-refresh hook of "immich-distribution" snap if present (run hook "pre-refresh": 
-----
Creating database backup: /var/snap/immich-distribution/common/backups/immich_database_v1.133.1_pgvectors.sql.xz

<exceeded maximum runtime of 10m0s>
-----)

To resolve this, follow these steps:

  1. Disable the hook by executing: touch /var/snap/immich-distribution/common/no-pre-refresh-hook
  2. Update as you normally would (for example, snap refresh).
  3. Restore the hook by executing: rm /var/snap/immich-distribution/common/no-pre-refresh-hook

Only users on the unstable edge, beta, or candidate channels need to perform these steps. This bug was identified during testing before it affected the stable channel.

Technical background

In preparation for the upcoming migration from pgvecto.rs to VectorChord, a database backup step was added to the pre-refresh hook. This hook is designed to back up the database before a snap update occurs. However, a bug was introduced in the pre-refresh script in revision 195 due to an incorrect path being committed.

Although a fix was implemented in the subsequent revision, users who had already updated to revision 195 found themselves stuck. This was because the pre-refresh hook runs before the update process, causing the update to fail repeatedly due to the faulty script.

Unfortunately, there was no way to automatically push a fix for this issue to affected users. Thankfully, a mechanism to disable the hook was already in place, which is the solution employed here.

Later, during further testing, it was discovered that on some systems, the database backup process could exceed the 10-minute timeout. This scenario would trigger a similar problem, effectively blocking the update.

Given these challenges, the decision has been made to revert this pre-refresh backup feature for now.

  • 1 min read

Upcoming database changes

Immich version 1.133.0 replaces the deprecated pgvecto.rs extension with its replacement VectorChord. To ease transition, Immich will support both in parallel for a few releases.

There is also a breaking change in the API between the mobile application and the server. With this in mind, I will fast-track this release and postpone the VectorChord change to a later, separate release.

Breaking change in the mobile app

Please ensure both your mobile app and the server are updated to v1.133.0. Older versions of the Immich mobile app will not work correctly with server version v1.133.0.

Upgrading from 1.107.2 or older

Due to the automatic updates in the package format, most users are on recent versions. Snap Store metrics show that only 0.5% of users are running releases this old. If you are one of these rare users, you need to manually update to a newer intermediate release before upgrading to the most recent release.

Database backup

There are a lot of database changes, which introduces some risk. If you have not done so already, this is probably a good time to enable automatic database backups. You can either use the built in backup job (should be enabled by default), or the backup tool included in this snap.

Use immich-distribution.backup -l to list existing backups.

  • 1 min read

Release update

I took a month for this release due an unusable buggy 1.125 release with six patch releases. The database layer has been swapped out in the upstream project and with a large change like this I was in no hurry to update. I also have a lot of personal things going on, so it fit me well to take a month of while it settled down a little.

I will release 1.126 directly to stable in a few days assuming I see no issues in my testing.