v2.3.1 - Could not load the "sharp" module using the linux-x64 runtime

[jenny923432]

I have searched the existing issues, both open and closed, to make sure this is not a duplicate report.

• Yes

The bug

After upgrading to 2.3.1, Immich cannot start because immich_server throws this error:

2025-12-09 05:11:53 Error: Could not load the "sharp" module using the linux-x64 runtime
2025-12-09 05:11:53 ERR_DLOPEN_FAILED: /usr/local/lib/libvips-cpp.so.42: file too short
2025-12-09 05:11:53 Possible solutions:
2025-12-09 05:11:53 - Ensure optional dependencies can be installed:
2025-12-09 05:11:53     npm install --include=optional sharp
2025-12-09 05:11:53 - Ensure your package manager supports multi-platform installation:
2025-12-09 05:11:53     See https://sharp.pixelplumbing.com/install#cross-platform
2025-12-09 05:11:53 - Add platform-specific dependencies:
2025-12-09 05:11:53     npm install --os=linux --cpu=x64 sharp
2025-12-09 05:11:53 - Consult the installation documentation:
2025-12-09 05:11:53     See https://sharp.pixelplumbing.com/install
2025-12-09 05:11:53     at Object.<anonymous> (/usr/src/app/server/node_modules/.pnpm/sharp@0.34.4/node_modules/sharp/lib/sharp.js:121:9)
2025-12-09 05:11:53     at Module._compile (node:internal/modules/cjs/loader:1688:14)
2025-12-09 05:11:53     at Object..js (node:internal/modules/cjs/loader:1820:10)
2025-12-09 05:11:53     at Module.load (node:internal/modules/cjs/loader:1423:32)
2025-12-09 05:11:53     at Function._load (node:internal/modules/cjs/loader:1246:12)
2025-12-09 05:11:53     at TracingChannel.traceSync (node:diagnostics_channel:322:14)
2025-12-09 05:11:53     at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
2025-12-09 05:11:53     at Module.require (node:internal/modules/cjs/loader:1445:12)
2025-12-09 05:11:53     at require (node:internal/modules/helpers:135:16)
2025-12-09 05:11:53     at Object.<anonymous> (/usr/src/app/server/node_modules/.pnpm/sharp@0.34.4/node_modules/sharp/lib/constructor.js:10:1)

Other people experiencing this issue on 1.x versions reported it clearing when they deleted the immich_server image and re-pulled it. That didn't help for me.

The OS that Immich Server is running on

Windows 11 Pro

Version of Immich Server

v2.3.1

Version of Immich Mobile App

0

Platform with the issue

• Server
• Web
• Mobile

Device make and model

No response

Your docker-compose.yml content

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
    volumes:
      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:8@sha256:81db6d39e1bba3b3ff32bd3a1b19a6d69690f94a3954ec131277b9a26b95b3aa
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always

volumes:
  model-cache:
  pgdata:

Your .env content

# You can find documentation for all the supported env variables at https://immich.app/docs/install/environment-variables

# The location where your uploaded files are stored
UPLOAD_LOCATION=o:/immich/library
# The location where your database files are stored
DB_DATA_LOCATION=pgdata

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
# TZ=Etc/UTC

# The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=release

# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=omitted

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Reproduction steps

1. docker compose up -d

Relevant log output

2025-12-09 05:11:53 Error: Could not load the "sharp" module using the linux-x64 runtime
2025-12-09 05:11:53 ERR_DLOPEN_FAILED: /usr/local/lib/libvips-cpp.so.42: file too short
2025-12-09 05:11:53 Possible solutions:
2025-12-09 05:11:53 - Ensure optional dependencies can be installed:
2025-12-09 05:11:53     npm install --include=optional sharp
2025-12-09 05:11:53 - Ensure your package manager supports multi-platform installation:
2025-12-09 05:11:53     See https://sharp.pixelplumbing.com/install#cross-platform
2025-12-09 05:11:53 - Add platform-specific dependencies:
2025-12-09 05:11:53     npm install --os=linux --cpu=x64 sharp
2025-12-09 05:11:53 - Consult the installation documentation:
2025-12-09 05:11:53     See https://sharp.pixelplumbing.com/install
2025-12-09 05:11:53     at Object.<anonymous> (/usr/src/app/server/node_modules/.pnpm/sharp@0.34.4/node_modules/sharp/lib/sharp.js:121:9)
2025-12-09 05:11:53     at Module._compile (node:internal/modules/cjs/loader:1688:14)
2025-12-09 05:11:53     at Object..js (node:internal/modules/cjs/loader:1820:10)
2025-12-09 05:11:53     at Module.load (node:internal/modules/cjs/loader:1423:32)
2025-12-09 05:11:53     at Function._load (node:internal/modules/cjs/loader:1246:12)
2025-12-09 05:11:53     at TracingChannel.traceSync (node:diagnostics_channel:322:14)
2025-12-09 05:11:53     at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
2025-12-09 05:11:53     at Module.require (node:internal/modules/cjs/loader:1445:12)
2025-12-09 05:11:53     at require (node:internal/modules/helpers:135:16)
2025-12-09 05:11:53     at Object.<anonymous> (/usr/src/app/server/node_modules/.pnpm/sharp@0.34.4/node_modules/sharp/lib/constructor.js:10:1)

Additional information

No response

[mmomjian]

Most likely the docker image is corrupted. Try docker compose down; docker image prune -a and then re pull the stack. We can re open if that does not fix it.

[jenny923432]

Unfortunately, that didn't fix it. docker compose down; docker image prune -a; docker compose pull && docker compose up -d, no change.

[mmomjian]

And when you re pulled it, it re downloaded all the images?

Please share more info on your setup - WSL, docker desktop, etc

[jenny923432]

Yep, it takes a minute to re-download all the images.

Version info:

Docker Desktop version: 4.54.0 (212467)

wsl --version:
WSL version: 2.6.2.0
Kernel version: 6.6.87.2-1
Windows version: 10.0.26200.7171
WSLg version: 1.0.71
MSRDC version: 1.2.6353
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release

Not sure what other information would be useful to provide.

[korneef]

Just in case it helps:

I stumbled upon this issue while solving my own but in a different environment. In my case problem was related with node-alpine version.

Node:20-alpine3.23 was released recently and sharp can't be installed on this version. I downgraded the node-alpine version in my docker-image to 3.22 and it works now.