Docker UPLOAD_LOCATION env variable

[jerkelens]

Hi,

Sorry for the many edits, I can't get code-blocks to parse properly...
Docker is running on my NAS and I have 2 storage pools;

1. RAID6 - generic storage
2. 2TB SSD - high speed docker, vm, etc.

I have immich running on pool 2, as a result all mobile immich uploads end up in ./library/uploads. However, I want to move these uploads to my other storage pool. I've searched the internet and this forum, and I found workarounds, but no real solution imho. I tried different setting in both docker_compose and the .env file, but I cannot for the life of me get this to work. Sorry, I'm pretty new to this .env impact. In my compose file I have:

    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}:/data
      < more data here >

As the comment states, I cannot change that particular line, so I edited the .env file:

# The location where your uploaded files are stored
UPLOAD_LOCATION=/volume1/media/uploads

This errors out as follows:

immich_server            | /usr/src/app/server/dist/services/storage.service.js:130
immich_server            |             throw new misc_1.ImmichStartupError(`Failed to read: "${externalPath} (${internalPath}) - ${docsMessage}"`);
immich_server            |                   ^
immich_server            | 
immich_server            | ImmichStartupError: Failed to read: "<UPLOAD_LOCATION>/encoded-video/.immich (/data/encoded-video/.immich) - Please see https://docs.immich.app/administration/system-integrity#folder-checks for more information."
immich_server            |     at StorageService.verifyReadAccess (/usr/src/app/server/dist/services/storage.service.js:130:19)
immich_server            |     at async /usr/src/app/server/dist/services/storage.service.js:57:21
immich_server            |     at async /usr/src/app/server/dist/repositories/database.repository.js:392:27
immich_server            |     at async /usr/src/app/server/node_modules/.pnpm/kysely@0.28.11/node_modules/kysely/dist/cjs/kysely.js:541:20
immich_server            |     at async DefaultConnectionProvider.provideConnection (/usr/src/app/server/node_modules/.pnpm/kysely@0.28.11/node_modules/kysely/dist/cjs/driver/default-connection-provider.js:12:20)
immich_server            |     at async /usr/src/app/server/dist/repositories/database.repository.js:389:13
immich_server            | 
immich_server            | Node.js v24.14.1

immich_server            | api worker exited with code 1```

I also tried to mount an additional path in the compose as follows:

      - /volume1/Media:/MyUploads
/volume1/Media is obviously accessible by my NAS.

And then use the .env-file to set the UPLOAD_LOCATION variable to:
./MyUploads

Redeploy this bunch, leads to the same error. 
I then tried to create the mentioned folder 'encoded-video' in the NAS mounted location, but this doesn't change a thing to the error.

Changing the UPLOAD_LOCATION to the local folder, ./library instantly fixes the error, but then again, I'm back at square one; uploaded files are placed on my wrong storage pool.

Really looking to understand why docker volumes aren't working as expected, and obviously some help to get this to work?
Thanks!

[Nickalus12]

To fix this error, ensure your new storage path is properly initialized and has the correct permissions for the Docker containers to access it.

Update .env and Initialize Directory

First, ensure your .env file uses an absolute path and that the directory exists on your NAS:

# In your .env file
UPLOAD_LOCATION=/volume1/media/uploads

Then, before starting the containers, you must manually create the internal folder structure that Immich expects for its health checks. Run these commands on your NAS:

# Create the directory
mkdir -p /volume1/media/uploads

# Create the hidden check files Immich requires
touch /volume1/media/uploads/.immich
mkdir -p /volume1/media/uploads/encoded-video
touch /volume1/media/uploads/encoded-video/.immich

# Ensure the Docker user has write permissions
chmod -R 775 /volume1/media/uploads
chown -R 1000:1000 /volume1/media/uploads 

Why this is happening

The ImmichStartupError occurs because Immich performs a safety check on startup. It looks for a hidden file named .immich in several subdirectories (like encoded-video, library, and upload) to verify that the storage is correctly mounted and writable.

When you changed the UPLOAD_LOCATION to a brand-new directory on pool 1, that directory was empty. Immich saw the missing .immich file and panicked to prevent data loss or "ghost" writes into a non-existent mount.

Important

If you are moving an existing library, you should move the entire contents of your old ./library folder (including the hidden .immich files) to the new location. If this is a fresh start, creating the empty files as shown above will satisfy the startup check.

Verify your Compose file

Ensure your docker-compose.yml uses the variable exactly as intended:

services:
  immich-server:
    # ...
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      # or if using the newer standard:
      - ${UPLOAD_LOCATION}:/data

Does the /volume1/media/uploads directory already contain files from a previous installation, or are you starting with a fresh library?

[jerkelens]

But what do I set folders to if I ONLY want the mobile-app uploaded photos to the custom upload location, and keep all other folders on their original location? (Assuming that's a supported scenario?).
Thanks!

[Nickalus12]

Yeah, that's supported — you can override specific subpaths via docker-compose volumes even if UPLOAD_LOCATION is set globally.

Keep UPLOAD_LOCATION pointing to your SSD pool (e.g. /volume2/immich). That keeps thumbs, encoded-video, profile, etc. on the fast drive by default.

Then in docker-compose.yml, add an explicit volume mount that overrides just the library folder:

volumes:
  - ${UPLOAD_LOCATION}:/usr/src/app/upload
  - /volume1/media/immich-library:/usr/src/app/upload/library

Mobile app uploads land in /library, so they'll go to your RAID pool. Everything else stays on the SSD where it's fast.

One thing to watch — existing uploads won't move automatically. You'd need to manually mv or rsync them to the new path and restart.

[jerkelens]

Ok so, I currently have:

• Only defaults in .env, including for the UPLOAD_LOCATION folder.
• Then used your 2 volume lines (according to my paths)

Then my photo backup from the mobile app is working, but the files don't appear on my NAS. The following path is used (according to photo properties through the webui of immich):
/usr/src/app/upload/upload/08c1f734-8f21-42c8-9cc9-8b020400c21d/cc/cb/cccb44f6-8412-4bf4-af8c-38c8fa0b90f4.jpg

I have upload/upload, you stated upload/library, my literal mount in compose is:
/volume1/Media/Uploads:/usr/src/app/upload/library

When checking the underlying file system, the file ends up in:
/volume2/docker/immich-1/library/upload/08c1f734-8f21-42c8-9cc9-8b020400c21d/cc/cb/cccb44f6-8412-4bf4-af8c-38c8fa0b90f4.jpg

Please note the 'volume2' portion, which is the docker root (SSD, not the HDD)
I'm in over my head, need your help again, thanks! :)

[Nickalus12]

Ah I see the issue — Immich puts mobile uploads at /usr/src/app/upload/upload, not /upload/library. So the volume mount needs to target that exact path:

volumes:
  - /volume1/Media/Uploads:/usr/src/app/upload/upload

That'll redirect mobile uploads to your HDD (volume1) while everything else stays on the SSD. After changing it, do a full restart (docker compose down && docker compose up -d) so the new mount takes effect.

You can verify it's working by uploading a test photo from the app and checking ls /volume1/Media/Uploads/ on your NAS — you should see the user UUID folder appear there.

[jerkelens]

Hi!

So I changed the relevant volume mounts to:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- /volume1/Media/Uploads:/usr/src/app/upload/upload

This seemed to do the trick! Uploads now go directly to the NAS! Thank you for your support @Nickalus12! Much appreciated!

[jerkelens]

Hi!

Thank you so much for your reply!
I ended up having to create this entire folder structure (with .immich in every one of them):

This cleared the error messages regarding the uploads folder. However after starting immich, it threw a new error:
immich_server | [Nest] 26 - 04/01/2026, 6:41:35 AM ERROR [Api:LoggingRepository~kgrjv17q] Unable to send file: Error: ENOENT: no such file or directory, access '/data/thumbs/08c1f734-8f21-42c8-9cc9-8b020400c21d/f3/0d/f30d56af-98df-4c0c-a6a7-5ab1ecdf03a5_thumbnail.webp'.

I read: https://docs.immich.app/guides/custom-locations/, which states:

.env

You can find documentation for all the supported environment variables [here](/install/environment-variables)

Custom location where your uploaded, thumbnails, and transcoded video files are stored
- UPLOAD_LOCATION=./library
+ UPLOAD_LOCATION=/custom/path/immich/immich_files
+ THUMB_LOCATION=/custom/path/immich/thumbs
+ ENCODED_VIDEO_LOCATION=/custom/path/immich/encoded-video
+ PROFILE_LOCATION=/custom/path/immich/profile
+ BACKUP_LOCATION=/custom/path/immich/backups
...```

I ONLY want to redirect mobile app uploaded files to the HDD pool, retain the others on the SSD pool. How should I accomplish that?
Thanks!