Image Storage Maintenance

InvokeAI can move existing images into the folder layout selected by image_subfolder_strategy. This is useful after changing the image subfolder strategy from flat to date, type, or hash, or when reorganizing an older image library.

This operation changes where image files and thumbnails are stored on disk. It does not change image names, boards, generation metadata, or gallery records.

Access

Open Settings → Server → Image storage. The Folder layout for new images select changes image_subfolder_strategy immediately for images saved from then on. Below it, Move existing images shows how many images are stored outside the current layout, the state of the last move job, and the Start Move and Recover buttons; each asks for confirmation before it starts.

• Start Move is available when images are stored outside the current layout and no interrupted job is waiting for recovery. The server still refuses it while any queue item is pending or in progress.
• Recover is available only when a move was interrupted and still needs finishing.
• Both buttons are unavailable while a job runs or a layout change is being saved. The status line or a note below the buttons says why a button is unavailable.

While a job runs and the Image storage setting is open, the status refreshes every few seconds and the folder layout cannot be changed. Closing Settings stops the refresh; reopen it to see the current state.

Administrators can start image moves, force recovery, and inspect the current move status. If multi-user mode is disabled, the single local user has the same access. Non-admin users in multi-user mode do not see the Server section and cannot run or inspect image move status.

Maintenance Mode

Image moves run as a maintenance operation. Before a move starts, InvokeAI checks that no queue work is active. While the move is running, or an interrupted move is waiting for recovery, InvokeAI prevents image reads, uploads, deletes, generation jobs, and gallery mutations from racing with the filesystem move.

The UI shows the move or recovery state until the job is complete or requires manual attention. Gallery images and thumbnails may be unavailable while maintenance is active; an open gallery keeps checking periodically while its tab is visible and reloads them on its own shortly after maintenance ends, so you do not need to refresh the page.

Crash Recovery

The move process is crash-recoverable. InvokeAI records each move job in its database before moving files, moves full-size images and thumbnails on disk, and updates images.image_subfolder only after the filesystem move succeeds.

If InvokeAI stops during a move, recovery resumes incomplete jobs. If recovery finds an ambiguous filesystem state, such as both the old and new full-size image files existing or neither file existing, it halts that item for manual repair instead of blindly updating the database. Other items in the same job are still finalized, and the maintenance lock is released when the job is recorded as failed.

Recovery finalizes jobs that were already recorded before the stop. Images that had not yet been planned into a move job are not moved by recovery itself. The Image storage setting reports how many images still need moving; run Start Move again to continue. While a job is interrupted, Start Move stays unavailable and the status asks you to run Recover first.

Missing intermediate image files are treated as already cleaned up and do not halt the move. Missing non-intermediate image files, unreadable images, and truncated images are recorded as failed items. When the full-size file is still at its original path, recovery leaves it there so it can be repaired or removed safely. If a previous filesystem move already placed the full-size file at its destination, recovery keeps that destination and reconciles the database before recording the item as failed. After recovery releases the lock, back up the failed file and either replace it with a valid image or delete its image record from the gallery, then run Start Move again if images still need moving. Do not delete an active journal row or edit images.image_subfolder while maintenance is active.

For the date strategy, existing images are moved according to their original image creation timestamp stored in the database, not according to the time the maintenance job is run.

Empty source directories left behind by successful moves are removed when safe.

Gallery maintenance

Gallery maintenance repairs mismatches between the gallery’s records and the image files on disk, for example after files were deleted by hand, or images were left behind by a deleted user. Administrators open it under Settings → Data & workspace → Gallery maintenance.

Action	What it does
Remove records for missing images	Deletes gallery records whose image file is missing, with their image-search (semantic index) entries. Thumbnails left behind go to the archive.
Archive untracked files	Moves image files that have no gallery record, and thumbnails without an image, to the archive.
Regenerate missing thumbnails	Creates missing thumbnails. Original images are unchanged.

Each action scans first and shows what it would change; nothing changes until you confirm, and the dialog waits until the action finishes. If the gallery changed since the scan, InvokeAI asks you to scan again. The actions cover images of every account, including images on archived boards and intermediates. They do not cover videos.

Before an action changes anything, it backs up the database, and the two archiving actions create an archive folder. The result shows both paths:

• Database backup: databases/backup/backup-<timestamp>-gallery-maintenance-<id>.db. With a MySQL or MariaDB database no backup is made; back it up with the server’s tools first.
• Archive (Remove records for missing images and Archive untracked files only): a new folder per run, outputs/images-archive/gallery-maintenance/<action>-<id>/.

Keep both until you are sure you will not need the removed records or archived files. Maintenance does not import archived files back into the gallery.