TrueNAS - Immich v1.137.1 migration to new storage configuration format
Built-in manual:
My locations:
- Postgres
-
/mnt/NVME/Apps/immich-app/pgData
- Upload:
- /mnt/Datastore/Immich/uploads
- Backups:
- /mnt/Datastore/Immich/backups
- Library:
- /mnt/Datastore/Immich/library
- Profile:
- /mnt/NVME/Apps/immich-app/profile
- Thumbs:
- /mnt/Datastore/Immich/thumbs
- Video:
- /mnt/Datastore/Immich/video
- Machine Learning Cache:
- /mnt/Datastore/Immich/MLcache
When I uncheck the box labeled Use Old Storage Configuration (Deprecated) only these options are visible:
- Data Storage (aka Upload Location)
- Why does it only show the path to Upload? Where are thumbs, library, profile, etc.?
- Machine Learning Cache
- I assume that here I can specify the location of the folder in the path/mnt/Datastore/Immich/MLcache
- Postgress Data Storage
- I assume that here I can specify the location of the folder in the path /mnt/NVME/Apps/immich-app/pgData
Can anyone advise me on exactly what to do?138 Replies
:wave: Hey @admo,
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 docs
- Container Status: 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
Checklist
I have...
1. :ballot_box_with_check: verified I'm on the latest release(note that mobile app releases may take some time).
2. :ballot_box_with_check: read applicable release notes.
3. :ballot_box_with_check: reviewed the FAQs for known issues.
4. :ballot_box_with_check: reviewed Github for known issues.
5. :ballot_box_with_check: tried accessing Immich via local ip (without a custom reverse proxy).
6. :ballot_box_with_check: uploaded the relevant information (see below).
7. :ballot_box_with_check: 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 and 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 command, and re-open it later if needed.
Successfully submitted, a tag has been added to inform contributors. :white_check_mark:Your postgres location is fine
MLcache, you can leave it to temporary
for the rest:
https://pr-19990.preview.immich.app/docs/install/truenas/#migrating-from-old-storage-configuration
TrueNAS [Community] | Immich
This is a community contribution and not officially supported by the Immich team, but included here for convenience.
The new storage location is "simplified" your datasets (thumbs, uploads and so one) are now folders of a main dataset
You can still separate them (as explained in the guide, there are 2 pages -W Migrate to a new dataset or keep existing dataset) so you could have your thumbs on a ssd pool for example
The thing that need to be updated in the guide is
rsync -av /mnt/tank/immich/video/ /mnt/tank/immich/data/video/
it shoud be
rsync -av /mnt/tank/immich/profile/ /mnt/tank/immich/data/profile/
rsync -av /mnt/tank/immich/video/ /mnt/tank/immich/data/encoded-video/
https://pr-19990.preview.immich.app/docs/install/truenas/ does not lead to anything ?
should data storage path in truenas point to /mnt/tank/new-immich/data or /mnt/tank/new-immich/data/upload ?
New link
/data not /data/upload
TrueNAS [Community] | Immich
This is a community contribution and not officially supported by the Immich team, but included here for convenience.
Thx! I thought I shared the right one, mb
No problem. Today I will try to migrate.
Everything works. Thank you for your help.
Good to know! Was the guide clear enough?
No issues with it?
hello, I am having trouble with the migration. I wanted to store the upload and library folders on my hdd pool while everything else is on ssd pool. I followed the guide above and copied the data from the old datasets to the new ones in the appropriate location. Then in the app config I mapped data storage to immich/data, and pgdata to immich/pgdata. I added additional datasets for the /data/upload and /data/library which are on my hdd pool. However, when I open immich, it appears that it wants a first time setup for admin registration instead of logging in with my user. I checked the /data folder and it appears to have auto created empty upload and library folders, so my theory is for some reason it's not seeing those folders on my hdd pool or maybe even overwriting some on the ssd pool? Is there something I'm doing wrong in the storage setup? Some screenshots attached for reference, thank you!!
could you give more details about what you did to copy the data from old to new?
Did you have host path for all, or also ix-volumes?
I was using ix-apps for most and copied using rsync (ex: rsync -av /mnt/.ix-apps/app_mounts/immich/profile/ /mnt/'SSD Pool'/immich/data/profile/). however, for uploads I was using host path on my hdd pool already, so I created a new upload folder and copied from the old one to the new one like this (rsync -av --exclude='uploads/' --exclude='library/' /mnt/Gus/Gus/Photos/ /mnt/Gus/Gus/Photos/upload/) A little funky i know, but I wanted to be able to store in the same Photos folder as before just with the upload subfolder being the one mounted now
I checked in the shell with ls and it appears the files copied to the destination directory successfully, including the upload folder (which was about 100gb in my case)
There is also the admin thing, it looks like it can't read the db either
Can you share your Immich config?
do you mean the yaml?
well the whoel TrueNAS edit section
yes i can do it in screenshots
could you also share the logs for both pgvecto and server containers?
sure here are the config screenshots:
I don't also understand your second rsync command? how did you move upload when you exlude it?
It runs as root, so it should not have issues to read the data
with the second rsync command, what I was doing is taking the folder I used to use for uploads, which in my case was /Photos, and creating a subfolder in /Photos called /upload and /library, where I wanted to copy each of that data respectivly. so I wanted to take the immich data from the root of /photos and move it to upload without moving the upload and library folders themselves as well. here are some screenshots of the folders to maybe help clarify
Oh yeah ok, I was confused by your terminolgy
So Photos is one dataset, and library and upload are folders inside this dataset, that makes more sense
yes sorry, I'm just learning about how all this stuff works and what the proper terminology is
No worries
here are the server logs by the way:
and here are the pgvecto logs
Can you check, inside the immich server container if, when you cd /data/upload
you can see your folders?
with "ls"
ill check
it looks like the folders are there
no .immich file though
yeah ls -a to see it
. means its hidden
so eveything seems to be working
The only issue would be the database migration that failed for some reason
While still inside this container, can you do ?
Yeah so no users
is there a folder i should check to make sure it migrated properly?
Well you could try to rsync the db again if you have not deleted it
Do you have backups of the database by any chances?
In Truenas could you do
?
can you do the same command but add pbBackup at the end of it?
btw, even though it look like you're comfortable with rsync commands
Could you share the one you ran to rsync the db? And I suppose it was as root that you ran it
sorry for delay, my boss walked over and i had to pretend like im working
for the rsync, these were all i ran: rsync -av /mnt/.ix-apps/app_mounts/immich/library/ /mnt/Gus/Gus/Photos/library/
rsync -av --exclude='uploads/' --exclude='library/' /mnt/Gus/Gus/Photos/ /mnt/Gus/Gus/Photos/upload/
rsync -av /mnt/.ix-apps/app_mounts/immich/thumbs/ /mnt/'SSD Pool'/immich/data/thumbs/
rsync -av /mnt/.ix-apps/app_mounts/immich/profile/ /mnt/'SSD Pool'/immich/data/profile/
rsync -av /mnt/.ix-apps/app_mounts/immich/video/ /mnt/'SSD Pool'/immich/data/encoded-video/
rsync -av /mnt/.ix-apps/app_mounts/immich/backups/ /mnt/'SSD Pool'/immich/data/backups/
becasue those were the folders on the instructions
can you
cd /mnt/.ix-apps/app_mounts/immich/pbBackup and then do ls inside?
where is pgData in all of that?
im not sure, i didn't see it on the migration instructions
well ok that's fine
Oh yeah MY bad on forgetting that on the guide
that explains it xD
its fully possible i missed it
wait no
In the tip section
The big green box at the beginning of the instrucitons
DO that
You have not moved your database so that is normal that you don't have anythjng
Do that with the Immich app shutdown
wow yeah i absolutely missed that step, i guess i thought for some reason that the database existed in the /data folder
And when it's up and running, you really should enable pgDump
https://my.immich.app/admin/system-settings?isOpen=backup
ok let me try these steps and im sure thatll fix my problem
hmm ok I copied the data with this command rsync -av /mnt/.ix-apps/app_mounts/immich/pgData/ /mnt/'SSD Pool'/immich/pgData and it seems like it successfully copied everything, but now the immich server won't start. It does go to "running" but then back to "deploying" and the web ui does not work
I actually had this same issue the first time i upgraded to the latest version, but i figured it was due to the new storage config. I rolled it back to make sure everything was still there and it worked fine.
Logs of pg vector ?
And if you can, also the ones of server if you can access it
server logs:
pgvecto logs: 2025-08-27 21:13:40.615078+00:00Using SSD storage
2025-08-27 21:13:40.638904+00:002025-08-27T21:13:40.638904935Z
2025-08-27 21:13:40.638924+00:00PostgreSQL Database directory appears to contain a database; Skipping initialization
2025-08-27 21:13:40.638932+00:002025-08-27T21:13:40.638932470Z
2025-08-27 21:13:40.648064+00:002025-08-27 21:13:40.648 GMT [1] LOG: skipping missing configuration file "/var/lib/postgresql/data/postgresql.override.conf"
2025-08-27 21:13:40.648329+00:002025-08-27 21:13:40.648 GMT [1] LOG: skipping missing configuration file "/var/lib/postgresql/data/postgresql.override.conf"
2025-08-27 21:13:40.669869+00:002025-08-27 14:13:40.669 PDT [1] LOG: starting PostgreSQL 15.14 (Debian 15.14-1.pgdg12+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14+deb12u1) 12.2.0, 64-bit
2025-08-27 21:13:40.670000+00:002025-08-27 14:13:40.669 PDT [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
2025-08-27 21:13:40.670019+00:002025-08-27 14:13:40.669 PDT [1] LOG: listening on IPv6 address "::", port 5432
2025-08-27 21:13:40.674347+00:002025-08-27 14:13:40.674 PDT [1] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
2025-08-27 21:13:40.680364+00:002025-08-27 14:13:40.680 PDT [21] LOG: database system was shut down at 2025-08-27 14:05:17 PDT
2025-08-27 21:13:40.688126+00:002025-08-27 14:13:40.688 PDT [1] LOG: database system is ready to accept connections
oh fck
Old version too
Come in this thread I'm explaining the same thing
https://discord.com/channels/979116623879368755/1410357104518369321
will do thank you
well I only begin to
@coburt if you encounter any issue, ask them here so the other thread is clean
(even though you already highjacked a resolved thread)
@coburt random thought, did you deleted the content of pgData before running the rsync command?
No I did not
I don't know if that would create any issue with the database as most it was empty, but maybe it could
If you think it would be best, I can delete and recopy before doing the Immich version change
Yes, do it, just to be 100% sure that nothing has been messed up
Ok thank you I will
Better safe than sorry 😄
Very true
Btw, lmk if you encouter any issue, or if everything went well!
I will! Not sure if I’ll finish it before the end of the day since I’m may have to do some actual work at work lol
No worries it's almost midnight where I live, so I won't see your answer before tomorrow
(sorry for the spam of pings in the other channel, but it's relevant)
well I could also have done that
Btw don't start the app before performing the version change, idk if that could modify stuff again
Will do, I’ve been keeping up on the other channel to make sure I get all the steps right too. I appreciate all of your help!
can you do
ls -la /mnt/Gus/Gus/Photos/library
I hopefully typed it correctlylooks right to me, ill try it now
you might need to do that as root
i am logged in as root
OH WAIT
YOU HAVE CUSTOM MOUNTS
ah yeah you mean because of the hdd and ssd pool?
Yes
So in your file
search for the things like /data/library
and replace the /data with /usr/src/app/upload
so for library it should be
/usr/src/app/upload/library
instead of
/data/library
Also make the change for upload
ohhhh because of the different storage system on the newer version
ok
so just for upload and library?
Yes
I don't think you had other custom mount
exactly
it was just those two
without changing the value, it created folders library and upload inside your hdd pool (they can exist, that won't change anything) but as they were not "initialised" the .immich is missing which throw this error
this is a good safeguard
https://immich.app/docs/administration/system-integrity/
If you want to read about it
Please tell me it works xD
does this look right? i wasn't sure on the /upload/upload
yeah yeah
the previous path was realtive and was in
uploadso upload/upload is normaland i keep the /app/upload in the other places I put it previously?
to replace /data
well /usr/src/app/upload byt yes
yeah sorry
thats what i meant
ok lets see if it works
Btw, why did you do your setup this way an not the other way around (like everything on HDD, and only thumbs and db on SSD)?
IT WORKED
NOICE
and ok for the ssd hdd i may have misunderstood, but my intention was to keep the full size images (which were all in my upload folder before) on the hdd
Check server logs to see if there isn't any migration or something like that
im not sure what to look for for the migration but here are the server logs:
Well if you want you can do it in the opposite way and have the files that don't need fast loading onto your hdd, and the rest on ssd
Can you access Immich?
yes
webui works and my pictures are all there
Ok that is great
Now, copy the whole custom yaml file and save it somewhere, this way we have an "easy rollback" if anything goes wrong
what i was thinking with the file layout is that the thumbnails are small and need to load quickly for my timeline performance, but the full size images are large and would fill up my ssd pool. I figured the db and everything else thats small should also live on ssd for app performance
But we could "fix" your structure so you don't waste space on your ssd
good idea
im open to a different structure for the folders if it makes sense
Yep, that is correct, however there is also encoded-video, which yeah might need to load fast, but they are video, so HDD are fine
i could definitly move encoded video to hdd
And also having the "backups" folder on a different pool than the database one, in IMO not a bad idea
(it's a backup only of the db if configured)
so doing backups, library, encoded video, and uploads on hdd, and all the rest on ssd?
Yes, also "profile" could be on HDD (it's the profile pic of user, so I don't think that they have to be loaded fast, I think they're probably cached)
Maybe you could rename your datasets, so its clearer
What I would do is like in the Truenas installation guide
So create a "parent" immich dataset with "generic permissions" in /mnt/Gus/Gus/
so you would have /mnt/Gus/Gus/Immich
Then create a child to this dataset like "data" with the "apps" preset
so /mnt/Gus/Gus/Immich/data
(you could also created (this is what I did) a separate dataset inside /mnt/Gus/Gus/Immich for encoded-video and another one for backup (it is just for replication/backup tasks so I only backup the essential which is in data and backups)
Then you'll have to run the rsync commands again, from your SSD pool and from you /mnt/Gus/Gus/Photos
So
rsync -av /mnt/Gus/Gus/Photos/upload/ /mnt/Gus/Gus/Immich/data/upload/
(don't forget the trailing /
and do this for every folders so
rsync -av /mnt/Gus/Gus/Photos/upload/ /mnt/Gus/Gus/Immich/data/upload/
rsync -av /mnt/Gus/Gus/Photos/library/ /mnt/Gus/Gus/Immich/data/library/
rsync -av /mnt/SSD/profile/ /mnt/Gus/Gus/Immich/data/profile/
rsync -av /mnt/SSD/encoded-video/ /mnt/Gus/Gus/Immich/data/encoded-video/
rsync -av /mnt/SSD/backups/ /mnt/Gus/Gus/Immich/data/backups
i think that all makes sense. would I want to upgrade the app to the new version first so that I can change the dataset mappings in the ui?
No
From 132 to latest, the breaking changes are handled by TrueNAS
So this should be fine to rsync the whole thing (and it's rsync so you could still "rollback" if there is any issue)
After that, you delete your custom immich app (thats why I told you to save the whole yaml)
Install a new immich instance, and instead of adding custom mount for upload and library, you do it for thumbs so
mount path:
/data/thumbs
host path:
/mnt/SSD/thumbs
If you create separate datasets for encoded-video and/or backups, you'll also have to mount them
so would I make the dataset changes, rsync from the existing datasets, and then change the mappings in the yaml first before changing back to the latest version and reinstalling truenas
all these datasets (except the Immich "parent" have to use the apps preset
no, simply delete the app, and reinstall it
ohh so we don't have to follow an upgrade path within the existing app?
the version we went to was already close enough to support upgrading to the latest one now?
Yes
gotcha
Breaking changes of 133 and 137 are "related" (related to database) and are "compatible"
and the breaking change in 136 is handled by trueNAS so 139 is ok to install
Otherwise, if any issue, you still have the "backup" of the yaml custom file
ok i think this all makes sense. pgData and thumbs are stored on ssd for performance. Everything else will live on HDD with its own proper immich dataset under Gus. I can make the dataset changes now and apply them to a new immich install on the latest version
Exactly
And if you have plan to make remote backups with another truenas (so replication)
I would suggest to create at least a separate dataset for your encoded-videos, as they're not essenttial and can be regenereated
you mean so I don't need to back them up with replication?
Yes
That's how It is set up on my end
ah that makes a lot of sense
backups also has it's own dataset in case I want to have a more robust backup policy for it for wathever reason
I think for my use cases since I don't have a replication target machine it would be simpler to just include it in the /data dataset for now, that way I don't have to split it up in the truenas config
but i do see the benefit in doing it your way
im not quite that deep into homelab yet haha
future proofing
Well you could just create the dataset later and rsync again if the needs arise
yeah good point
(I don't have a remote replication target yet, I only have a local one to a second pool)
thats a good idea too, I just dont have enough hard drives or space in my case for them yet. In the future i want to convince some friends to build their own truenas machines and create ssh tunnels to replicate offsite with them
but thats far off right now haha
well anyway, I've gotta leave work now but when I have time ill try to get the datasets sorted and get everything reinstalled on the latest version
thank you again for your help, you're really a lifesaver
No problem! I'll have to go to bed anyway (2am here)
jeez thats brutal
Keep me up to date, so I can help you clean up everything else too
I sure will, is this an ok thread to keep using?
And I still have to make my master thesis defense prensatation (that's why I really should go to bed, even though I really like to help)
yeah I mean it is longer than the original one so…
wow good luck on that! very impressive
Oh I forgot
If you do end up doing migration + deploy latest
Your thumbs might be blurry, so check logs of server, if there is an issue with missing path upload/…
I'll have to do https://discord.com/channels/979116623879368755/1401229113641009204/1401303535370506402
Update: probably not necessary as you skip the TrueNAS version that created the issue
Hey @Xiticks just wanted to let you know that everything worked! I'm on the lastest version of immich with the new dataset structure you recommended. Performance seems good, and the mobile app + my reverse proxy works too!
Thank you so much for your time and help on this
Nice! I was about to ask
Try to be relatively up to date while Immich is still not stable
Well I did not help for reverse proxy or app, so I hope it was working well
Yeah i was just saying that you never know when updates can break other things in the chain too haha
I saw on the roadmap that immich is hoping to go stable this year?
do you know anything about when that might happen?
I don't have any insight, sorry, but I suppose by the end of the year haha
Well you can follow the releases on github and there is a red section with breaking changes, even though, most of the time everything is handled by TrueNAS so you don't have anything to do aside from clicking on the update button
Btw if you need/want help to clean the old data altogether (even the now useless ix_volumes, I can help with that during the weekend
And even when Immich hits stable, I would still recommend to update at least every 2 months
I will give it a shot to clean up the old data, especially the multiple duplicates of the upload folder I have, but I’ll be sure to let you know if I run into issues. Now I’m on to fixing the next broken thing on my server which is Nextcloud haha
How did you manage to break it? -_-
Good luck with that 🙂
Well it’s not fully broken but I’m trying to get the collabora server to connect so I can edit documents and stuff
Oh yeah, it is not fun to set up, I struggled to do it too
Do you know of any forums or discord servers for Nextcloud that would be helpful? I did some research and since Nextcloud is more enterprise focused there’s less of a passionate community of support out there for home users
Not that I can remember, I’ll have a look during the weekend if I saved some guides or if I just did trial and errors