checkDiskUsage function reports wrong disc stats

[sletkeman]

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

• Yes

The bug

On the UI and in the app, the storage space has always been reported incorrectly. I dug around a little and noticed that when there is no user quota, the stats come from the function async checkDiskUsage(folder: string) in storage.repository.ts. That function is calling fs.statfs which gives erroneous results. I would imagine it happens because statfs is being called on a folder which is volume mounted to the docker container. I'm running Immich on a Mac Mini. I have a 2 TB RAID 1 volume mounted for my image storage.

The OS that Immich Server is running on

OSX Sequoia 15.2

Version of Immich Server

v1.131.3

Version of Immich Mobile App

v1.131.3 build.201

Platform with the issue

• Server
• Web
• Mobile

Your docker-compose.yml content

#
# WARNING: Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.
#

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}:/usr/src/app/upload
      - /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, openvino] 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://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, openvino, openvino-wsl] 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/redis:6.2-alpine@sha256:eaba718fecd1196d88533de7ba49bf903ad33664a92debb24660a922ecd9cac8
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:90724186f0a3517cf6914295b5ab410db9ce23190a2d9d0b9dd6463e3fa298f0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    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
    healthcheck:
      test: >-
        pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" || exit 1;
        Chksum="$$(psql --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" --tuples-only --no-align
        --command='SELECT COALESCE(SUM(checksum_failures), 0) FROM pg_stat_database')";
        echo "checksum failure count is $$Chksum";
        [ "$$Chksum" = '0' ] || exit 1
      interval: 5m
      start_interval: 30s
      start_period: 5m
    command: >-
      postgres
      -c shared_preload_libraries=vectors.so
      -c 'search_path="$$user", public, vectors'
      -c logging_collector=on
      -c max_wal_size=2GB
      -c shared_buffers=512MB
      -c wal_compression=on
    restart: always

volumes:
  model-cache:

Your .env content

LOG_LEVEL=debug

# 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=/Volumes/Scott_RAID1/immichUploads
# The location where your database files are stored
DB_DATA_LOCATION=/Volumes/Scott_RAID1/immichPostgres

# 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=immich

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

Reproduction steps

...

Relevant log output

Additional information

No response

[dgilperez]

Heads up — the Node.js fix nodejs/node#62277 ("fs: expose frsize field in statfs", semver-minor) was merged on 2026-03-31. Once the Immich server image rebuilds on a Node release that includes it (currently ships Node v24.14.1), the fix here is a one-line change: use frsize instead of bsize in checkDiskUsage.

PR #27375 proposed a stat shell-out and was closed after @bo0tzz pointed at fixing it upstream, which has now happened.

Root cause confirmed here (macOS + colima, virtiofs)

$ docker exec immich_server stat -f --format 'bsize=%s frsize=%S blocks=%b' /usr/src/app/upload
bsize=1048576 frsize=4096 blocks=1220934139

• blocks × bsize = 1.22 PB → what the UI shows
• blocks × frsize = 4.66 TB → what df -h shows (correct)
• Exactly 256×. Same pattern in borg#4289 and cockroachdb#61182.

Workaround until the Node bump lands

No rebuild needed. Shells out to df:

mkdir -p ~/immich-patches
docker cp immich_server:/usr/src/app/server/dist/repositories/storage.repository.js \
  ~/immich-patches/storage.repository.js

Replace checkDiskUsage in that file with:

async checkDiskUsage(folder) {
    try {
        const { execFile } = require("node:child_process");
        const { promisify } = require("node:util");
        const execFileP = promisify(execFile);
        const { stdout } = await execFileP("df", ["-k", "-P", folder]);
        const line = stdout.trim().split("\n")[1];
        if (line) {
            const parts = line.split(/\s+/);
            const totalK = Number.parseInt(parts[1], 10);
            const usedK = Number.parseInt(parts[2], 10);
            const availK = Number.parseInt(parts[3], 10);
            if (Number.isFinite(totalK) && Number.isFinite(usedK) && Number.isFinite(availK)) {
                const K = 1024;
                return { available: availK * K, free: (totalK - usedK) * K, total: totalK * K };
            }
        }
    } catch { /* fall through to statfs */ }
    const stats = await promises_1.default.statfs(folder);
    return {
        available: stats.bavail * stats.bsize,
        free: stats.bfree * stats.bsize,
        total: stats.blocks * stats.bsize,
    };
}

Mount it over the original:

# docker-compose.override.yml
services:
  immich-server:
    volumes:
      - ./immich-patches/storage.repository.js:/usr/src/app/server/dist/repositories/storage.repository.js:ro

docker compose up -d. Went from 278.8 TiB / 1.1 PiB to 1.1 TiB / 4.5 TiB, matches host df -h.

If it helps, I can send the bsize → frsize PR once Immich bumps Node to a release with #62277.

[bo0tzz]

It doesn't look to me like that node PR is targeted for backporting to 24.x, so it'd probably be quite a while before it lands in Immich.

[dgilperez]

I am happy to send a PR with my local fix, but I see similar attempts where closed before?

[bo0tzz]

The fix is to use this change in node, I'm just aligning expectations on how long that might take if it doesn't get a backport.

[MarcelMaxx]

Confirmed this still reproduces on Immich v3.0.3 with OrbStack 2.2.1 on an Intel Mac running macOS.

Setup: an external HDD is bind-mounted at /data/library. The Immich UI reports 1.5 PiB used / 3.6 PiB total, while df -h /data/library inside the container reports approximately 779 GiB used / 1.9 TiB total.

Exact values observed:

Node v24.14.1 fs.statfs(/data/library):
bsize = 1048576
blocks = 3906494720

/usr/bin/stat -f -c %S /data/library:
frsize = 512

The current checkDiskUsage calculation uses blocks * bsize. On this OrbStack/FUSE mount, the block counts are denominated in frsize units, so the displayed capacity is inflated by exactly 2048x:

3906494720 * 1048576 ≈ 3.6 PiB   (current result)
3906494720 * 512 = 2000125296640 bytes ≈ 1.8 TiB   (correct result)

I verified this locally with a compatibility shim that substitutes stat -f -c %S for bsize. Immich then reports 778.7 GiB / 1.8 TiB (41.8%), matching both the host and container df output.

Node v24.14.1 does not expose frsize; nodejs/node#62277 added it in Node 26.1.0. Once Immich uses a Node version exposing that field, checkDiskUsage should use stats.frsize ?? stats.bsize and ideally include a regression test where bsize !== frsize.

This appears to be the same root cause, with an OrbStack-specific reproduction and a 2048x inflation factor.