feat: integrity check jobs (missing files, untracked files, checksums) by insertish · Pull Request #24205 · immich-app/immich

insertish · 2025-11-26T17:38:18Z

Adds integrity check jobs:
- Find missing files: Finds assets or asset files which are missing files on system. Checks all every day by default.
- Find untracked files: Finds stray files not attached to either assets / asset files. Checks all every day by default.
- Check checksums: Find assets whose checksum does not match source file. Maintains a continuous queue through all files which runs in batches for 1 hour each day by default.
Users can view integrity reports from the maintenance settings.
- Each report can be viewed as a table, downloaded as a CSV, and re-run.
- Individual entries in the reports can be downloaded (if applicable), deleted (removing underlying file or trashing asset).
- Entire reports can be cleared (deleting all underlying files or trashing all assets).

How Has This Been Tested?

Service tests for integrity service.
Updated some tests where necessary. (job, queue, system-config)
e2e integration tests for API
e2e integration test for the integrity page

Screenshots

Screencast_20260107_131048.webm

Checklist:

I have performed a self-review of my own code
I have made corresponding changes to the documentation if applicable
I have no unrelated changes in the PR.
I have confirmed that any new dependencies are strictly necessary.
I have written tests for new code (if applicable)
I have followed naming conventions/patterns in the surrounding code
All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

Please describe to which degree, if any, an LLM was used in creating this pull request.

Used to figure out some of the types in the SQL query builder syntax.
Used as a starting point for some research into Postgres / SQL query performance.

Future Work

Send notifications to user if issues are detected.
The manual job implementation is a little messy, this will be fixed by feat: create job with data dto #25204.

refactor: rename checksum_fail to checksum_mismatched

refactor: combine the stream query

chore: lint & format

feat: update summary after job runs

Signed-off-by: izzy <me@insrt.uk>

…-izzy

Signed-off-by: izzy <me@insrt.uk>

fix: should provide arrow function to , oops! Signed-off-by: izzy <me@insrt.uk>

Signed-off-by: izzy <me@insrt.uk>

danieldietzler · 2026-02-12T15:37:12Z

web/src/lib/components/maintenance/integrity/IntegrityReportTableItem.svelte

+    type?: IntegrityReportType;
+    isDeleting: boolean;
+  }) => {
+    if (type === reportType || reportId === id) {


Isn't the id globally unique? Is it only unique for a given report type?

Yes it's globally unique.
This check succeeds if:

type? is present, i.e. "delete all" triggered for a type

reportId? is present, i.e. this specific report is being deleted

I misread this as an && 🤦

web/src/routes/admin/maintenance/+page.svelte

…-izzy

Signed-off-by: izzy <me@insrt.uk>

…-izzy

Signed-off-by: izzy <me@insrt.uk>

danieldietzler

The code looks great to me. Handing it off to @jrasm91 :D

danieldietzler · 2026-03-02T11:17:53Z

server/src/repositories/integrity.repository.ts

+          .where('asset.deletedAt', 'is', null)
+          .select(['asset.originalPath as path'])
+          .select((eb) => [
+            eb.ref('asset.id').$castTo<string | null>().as('assetId'),


Now that you cast the end result to something much more meaningful, you also don't need these casts anymore. (+ the sql template strings don't need to be typed as string | null if they're always null

danieldietzler · 2026-03-02T11:19:52Z

server/src/services/integrity.service.ts

+    },
+  }: ArgOf<'ConfigInit'>) {
+    this.integrityLock = await this.databaseRepository.tryLock(DatabaseLock.IntegrityCheck);
+    if (this.integrityLock) {


Maybe change this to if (!this.integrityLock) { return; } so that the entire function body does not need to be in that if

danieldietzler · 2026-03-02T11:21:06Z

server/src/services/integrity.service.ts

+  }
+
+  getIntegrityReport(dto: IntegrityGetReportDto): Promise<IntegrityReportResponseDto> {
+    return this.integrityRepository.getIntegrityReport({ cursor: dto.cursor, limit: dto.limit || 100 }, dto.type);


If I set a limit of 0, this will give me the first 100 reports. Do you want ?? 100 instead, or is this intentional?

danieldietzler · 2026-03-02T11:36:42Z

server/src/services/integrity.service.ts

+      date: lastCreatedAt?.toISOString(),
+    });
+
+    printStats();


Why does printStats even need to be a function? You're only calling it once

danieldietzler · 2026-03-02T11:37:51Z

server/src/services/integrity.service.ts

+    const byAsset = reports.filter((report) => report.assetId);
+    const byFileAsset = reports.filter((report) => report.fileAssetId);
+    const byPath = reports.filter((report) => !report.assetId && !report.fileAssetId);


This is cursed lmao

LeLunZ · 2026-03-04T17:02:13Z

Suggestions:

Wouldn't it make sense to make these integrity checks also be part of the "restoring from db dump/backup" process, so you can directly verify after a restore if there are missing assets in your database or in your filesystem?

Also for assets that are on the filesystem but not in the database, it would be nice if they can be re-uploaded through immich itself, so you don't have to press "download", get them on your device, and then re-upload, but just press "import" or similar.

akostadinov · 2026-03-27T17:09:18Z

Will this catch instances of:

Unable to run job handler (thumbnailGeneration/generate-jpeg-thumbnail): Error: Input file contains unsupported image format

See #7082 for more discussion. Thank you!

insertish added 2 commits November 26, 2025 15:45

stash: integrity checks

f77f43a

refactor: batched integrity checks

4a7120c

immich-push-o-matic bot added the 🗄️server label Nov 26, 2025

insertish added the changelog:feature label Nov 27, 2025

insertish added 15 commits November 27, 2025 12:00

feat: checksum job

3414210

chore: open api

15503b1

feat: write integrity report to database

1e941f3

feat: add createdAt to integrity report table

929ad52

refactor: rename checksum_fail to checksum_mismatched

feat: clean up old reports of checksum or missing files

cc31b9c

refactor: combine the stream query

feat: check orphaned file reports are not out of date

ef7d8e9

chore: open api

1744237

feat: add config options & cron entries for checks

9386023

fix: mock the new repository

2516319

revert: override migration db url

919eb83

chore: generate SQL queries

4462683

fix: add integrity report repository to service depends.

03276de

fix: add mock for asset repo.

8db6132

feat: draft controller entry

0fdc7b4

chore: lint & format

feat: view integrity report in maintenance page (cherry picked)

d3abed3

immich-push-o-matic bot added the 🖥️web label Nov 27, 2025

insertish added 10 commits November 28, 2025 11:40

feat: sub-pages for integrity reports

ca358f4

chore: remove old table comment

c50118e

stash: moving computers because pnpm is cooked

13e9cf0

feat: manually trigger integrity jobs

2779fce

feat: update summary after job runs

chore: sort i18n

e447ba8

feat: refresh missing & checksum

4d7f7b8

test: take baseline, check for each issue, check refreshes work

0362d21

stash: incomplete checksum outdated test

c4ac8d9

test: serialise the buffer over events

01f96de

chore: lint

1daf1b4

insertish added 11 commits February 11, 2026 15:54

refactor: prefer type over interface

cc7d8f2

Signed-off-by: izzy <me@insrt.uk>

Merge remote-tracking branch 'origin/main' into feat/integrity-checks…

a1812e9

…-izzy

chore: update readme/sql

477d432

Signed-off-by: izzy <me@insrt.uk>

refactor: review suggestions for web/../integrity.service.ts

8cb63eb

Signed-off-by: izzy <me@insrt.uk>

chore: update icon for integrity checks queue

5ed0ff4

Signed-off-by: izzy <me@insrt.uk>

refactor: use GET/Query for report fetch

fbdeb04

Signed-off-by: izzy <me@insrt.uk>

refactor: pass only userId to deleteIntegrityReport

4908289

Signed-off-by: izzy <me@insrt.uk>

refactor: arrow functions in svelte components

bf17d8c

fix: should provide arrow function to , oops! Signed-off-by: izzy <me@insrt.uk>

refactor: split refresh into private functions

c5fb13e

Signed-off-by: izzy <me@insrt.uk>

refactor: split asset checksum check into private func.

6b7ac81

Signed-off-by: izzy <me@insrt.uk>

refactor: use makeStream for 2nd case; update makeStream type

f6d88ff

Signed-off-by: izzy <me@insrt.uk>

danieldietzler reviewed Feb 12, 2026

View reviewed changes

insertish added 10 commits February 24, 2026 17:08

Merge remote-tracking branch 'origin/main' into feat/integrity-checks…

a44a886

…-izzy

chore: openapi

f4ccf18

chore: remove uppercase from UI

df51bea

chore: change variable name casing

e32ed6c

refactor: use medium tests for integrity service

0a35809

Signed-off-by: izzy <me@insrt.uk>

refactor: stricter repository typing

891a3c8

Signed-off-by: izzy <me@insrt.uk>

Merge remote-tracking branch 'origin/main' into feat/integrity-checks…

1812248

…-izzy

fix: use @immich/sql-tools

6f35ab9

Signed-off-by: izzy <me@insrt.uk>

chore: open api

50eea11

Signed-off-by: izzy <me@insrt.uk>

chore: sql query was renamed

a7045b3

danieldietzler approved these changes Mar 2, 2026

View reviewed changes

danieldietzler requested a review from jrasm91 March 2, 2026 11:48

alextran1502 mentioned this pull request Mar 12, 2026

fix(server): sync files to disk #26881

Merged

This was referenced Mar 27, 2026

Missing asset file after upload from mobile #26720

Closed

Constantly reuploads corrupted images #25126

Closed

System integrity feature #12293

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: integrity check jobs (missing files, untracked files, checksums)#24205

feat: integrity check jobs (missing files, untracked files, checksums)#24205
insertish wants to merge 140 commits intomainfrom
feat/integrity-checks-izzy

insertish commented Nov 26, 2025 •

edited

Loading

Uh oh!

danieldietzler Feb 12, 2026

Uh oh!

insertish Feb 25, 2026

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

Uh oh!

Uh oh!

danieldietzler left a comment

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

danieldietzler Mar 2, 2026

Uh oh!

LeLunZ commented Mar 4, 2026 •

edited

Loading

Uh oh!

akostadinov commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

insertish commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How Has This Been Tested?

Screenshots

Checklist:

Please describe to which degree, if any, an LLM was used in creating this pull request.

Future Work

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

danieldietzler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeLunZ commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

akostadinov commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

insertish commented Nov 26, 2025 •

edited

Loading

LeLunZ commented Mar 4, 2026 •

edited

Loading