Immich•8mo ago

How is the storage template engine supposed to work?

Hello everyone! Apologies if this has been discussed elsewhere—I couldn’t find a definitive answer on GitHub, in the issues, or on Discord. I’ve read the storage-template docs (https://immich.app/docs/administration/storage-template) and everything else I could find online, but I’m still puzzled by how this feature works in practice. I’ve set up Immich several times, and I’m not sure whether this is intended behavior, an issue with my setup, or simply my own unrealistic expectations. Please enlighten me!
My docker-compose.yml: https://cloud.taking.pictures/s/qGG8cxSKgZQsAHS

From the docs and the UI, I expected the storage template to:

Replicate any album structure I create in Immich (via web or mobile) into my filesystem, according to my template settings
Automatically apply changes to the filesystem whenever I move a file between albums or add a file to an album
Essentially run the “migrate storage template” job on every asset change, so that my filesystem always (near real-time) mirrors my album structure

What I actually see is that no replication occurs unless I manually trigger the migration job in the web UI. In the logs, I only see this output when I run it manually—I had hoped it would run automatically whenever I move an asset or edit an album:

LOG [Microservices:StorageTemplateService] Starting storage template migration  
LOG [Microservices:StorageTemplateService] Finished storage template migration

LOG [Microservices:StorageTemplateService] Starting storage template migration  
LOG [Microservices:StorageTemplateService] Finished storage template migration

LOG [Microservices:StorageTemplateService] Starting storage template migration  
LOG [Microservices:StorageTemplateService] Finished storage template migration

LOG [Microservices:StorageTemplateService] Starting storage template migration  
LOG [Microservices:StorageTemplateService] Finished storage template migration

Is this the intended behavior? If automatic triggering isn’t supported, could I instead use the Immich CLI in a cron job to run migrations at regular intervals, so that my filesystem stays in sync at all times?

I would greatly appreciate your insights on this matter.
Thank you in advance!

Immich•5/13/25, 9:12 AM

:wave: Hey @HolyMacarony,

Thanks for reaching out to us. Please carefully read this message and follow the recommended actions. This will help us be more effective in our support effort and leave more time for building Immich :immich:.

References

Container Logs:
```
docker compose logs
```
```
docker compose logs
```
docs
Container Status:
```
docker ps -a
```
```
docker ps -a
```
docs
Reverse Proxy: https://immich.app/docs/administration/reverse-proxy
Code Formatting https://support.discord.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline#h_01GY0DAKGXDEHE263BCAYEGFJA

Immich•5/13/25, 9:12 AM

Checklist

I have...

:blue_square: verified I'm on the latest release(note that mobile app releases may take some time).
:blue_square: read applicable release notes.
:blue_square: reviewed the FAQs for known issues.
:blue_square: reviewed Github for known issues.
:blue_square: tried accessing Immich via local ip (without a custom reverse proxy).
:blue_square: uploaded the relevant information (see below).
:blue_square: tried an incognito window, disabled extensions, cleared mobile app cache, logged out and back in, different browsers, etc. as applicable

(an item can be marked as "complete" by reacting with the appropriate number)

Information

In order to be able to effectively help you, we need you to provide clear information to show what the problem is. The exact details needed vary per case, but here is a list of things to consider:

Your docker-compose.yml and .env files.
Logs from all the containers and their status (see above).
All the troubleshooting steps you've tried so far.
Any recent changes you've made to Immich or your system.
Details about your system (both software/OS and hardware).
Details about your storage (filesystems, type of disks, output of commands like
```
fdisk -l
```
```
fdisk -l
```
and
```
df -h
```
```
df -h
```
).
The version of the Immich server, mobile app, and other relevant pieces.
Any other information that you think might be relevant.

Please paste files and logs with proper code formatting, and especially avoid blurry screenshots.
Without the right information we can't work out what the problem is. Help us help you ;)

If this ticket can be closed you can use the

/close

/close

command, and re-open it later if needed.

Zeus•5/13/25, 10:05 AM

It runs nightly

Zeus•5/13/25, 10:06 AM

(I think)
Definitely not on every change

Zeus•5/13/25, 10:10 AM

You could use the API to run it more often, like hourly. I wouldn’t do it every minute. It’s not that optimized

HolyMacaronyOP•5/13/25, 11:12 AM

Thank you for your answer, Zeus. I just want to be sure that the “migrate storage template” job is triggered automatically at least once a day. Otherwise, keeping the filesystem in sync with the album structure would require manual intervention every time, which would quickly become tedious. Is there any documentation or resource that outlines the scheduling of this and other periodic jobs in Immich so I can confirm how often they run?

HolyMacaronyOP•5/13/25, 11:13 AM

And i guess it is this API call you are referring to? https://immich.app/docs/api/send-job-command/

Zeus•5/13/25, 11:25 AM

I would just wait 24-48 hours and check on disk, or you can monitor the logs

HolyMacaronyOP•5/13/25, 11:30 AM

Yes i'll do both. Thanks!

HHolyMacarony Thank you for your answer, Zeus. I just want to be sure that the “migrate storag...

NoMachine•5/13/25, 5:17 PM

all jobs runs at midnight, except from the storage migration job, that one isn't scheduled.

in the meantime you can create a daily cron job to force it

curl -L -X PUT 'http://localhost:2283/api/jobs/storageTemplateMigration' \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json' \
        -H 'x-api-key: XXXXXXXXXXX' \
        -d '{
          "command": "start",
          "force": false
        }'

curl -L -X PUT 'http://localhost:2283/api/jobs/storageTemplateMigration' \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json' \
        -H 'x-api-key: XXXXXXXXXXX' \
        -d '{
          "command": "start",
          "force": false
        }'

HolyMacaronyOP•5/13/25, 7:00 PM

Thank you! That’s exactly what I thought. I already did that, and it worked flawlessly. Isn’t that something that should be integrated into Immich natively as well? Otherwise, you’ll never have consistency between your album structure and the filesystem unless you trigger it manually.

How is the storage template engine supposed to work?

References

Checklist

Information

Similar Threads

Similar Threads

References

Checklist

Information

Similar Threads