Using the template files from Immich doesn't work

[topaz obsidian]

To Immich Customer Support,

I downloaded the latest docker-compose.yml and the .env template files from Immich GitHub, and I only changed one line of code in the .env file to se the time to TZ=America/Los_Angeles, and added the folder location for the upload subfolder to my hard drive: UPLOAD_LOCATION=F:/Photos_backup/Immich/upload

But, after getting the program running, and enter the URL of http://(my wifi IP4 address):2283, or http://localhost:2283, the browser seems to try to connect for few seconds and then shows a blank page with an error of "This page isn’t working, IP didn’t send any data, and ERR_EMPTY_RESPONSE"

So I started two sessions with AI tools trying to troubleshoot, one with ChatGPT and one with Gemini, each with many hours of modifying the code and trying all kinds of reset, and could not make it work after two days. Both AI tools eventually telling me to give up on this seemingly fragile app and try some other programs.

This is Gimini's summary for reporting the issue to Immchi:
Let them know the following:

1. Environment: Docker Desktop on Windows (WSL2 backend).
2. The Core Issue: The server container is ignoring IMMICH_HOST=0.0.0.0 (set in both .env and docker-compose.yml) and is defaulting to 127.0.0.1:2283.
3. Drive Setup: You are using an external drive (F:) for both library and database storage.
4. Version: ghcr.io/immich-app/immich-server:release (v2.4.1 according to your logs).
5. Symptoms: docker ps shows the ports are mapped, but the logs confirm the internal bind is loopback-only.

It has been a very frustrating experience trying to get this working. Before I totally giving up on using this, I'd like to hear someone from Immchi exactly what's your diagnose...

• Why your own template files does not work? - Didn't someone in your team tested this fully on Windows 11?
• Why Immich seems to be stuck only listening to port 127?
• What other troubleshooting steps I can try?

Thanks!

[karmic willow]

:wave: Hey @topaz obsidian,

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 .

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. :blue_square: verified I'm on the latest release(note that mobile app releases may take some time).
2. :blue_square: read applicable release notes.
3. :blue_square: reviewed the FAQs for known issues.
4. :blue_square: reviewed Github for known issues.
5. :blue_square: tried accessing Immich via local ip (without a custom reverse proxy).
6. :blue_square: uploaded the relevant information (see below).
7. :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 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.

[topaz obsidian]

More info:
docker ps command displays the following:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
7557fac5b7ac ghcr.io/immich-app/immich-server:v2 "tini -- /bin/bash -…" 21 minutes ago Up 20 minutes (healthy) 2283/tcp immich_server
deeaa20308c6 ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 "/usr/local/bin/immi…" 21 minutes ago Up 21 minutes (healthy) 5432/tcp immich_postgres
bbe20ee647ac ghcr.io/immich-app/immich-machine-learning:v2 "tini -- python -m i…" 21 minutes ago Up 21 minutes (healthy) immich_machine_learning
72a8dad9db34 valkey/valkey:9 "docker-entrypoint.s…" 21 minutes ago Up 21 minutes (healthy) 6379/tcp immich_redis

[topaz obsidian]

"docker logs immich_server --tail 20" displays the following:
"configFile": false,
"email": false
}
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:SystemConfigService] LogLevel=log (set via system config)
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:MachineLearningRepository] Machine learning server became healthy (http://immich-machine-learning:3003).
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:NestFactory] Starting Nest application...
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] BullModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] ClsModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] ClsCommonModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] KyselyModule$1 dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] OpenTelemetryModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] KyselyCoreModule$1 dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] DiscoveryModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] OpenTelemetryCoreModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] ClsRootModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] BullModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] BullModule dependencies initialized
[Nest] 7 - 12/20/2025, 1:57:32 PM LOG [Microservices:InstanceLoader] MicroservicesModule dependencies initialized

[topaz obsidian]

Gemini further summarized the issues as the following:

• Immich Server defaulting to 127.0.0.1 on Windows WSL2 (v2.4.1)
  Context:
• OS: Windows 11 / Windows 10
• Docker Version: Docker Desktop (WSL2 Backend)
• Immich Version: v2.4.1 (release)
• Storage: All data (Uploads & Postgres) mapped to an external drive (F:/).
• The Problem: Despite setting IMMICH_HOST=0.0.0.0 in both the .env file and the docker-compose.yml, the immich_server container stubbornly binds to 127.0.0.1:2283. This prevents the Windows host browser from accessing the service at http://localhost:8081, even though docker ps shows the ports are correctly mapped.

Troubleshooting Steps Taken So Far:

• Environment Variables: Confirmed IMMICH_HOST=0.0.0.0 and IMMICH_PORT=2283 are present in .env.
• YAML Overrides: Added environment: block to immich_server in docker-compose.yml to force the variables.
• Command Injection: Attempted to override the entrypoint with command: /usr/src/app/start-server.sh, which resulted in an Exit 127 (Command not found).
• Network Reset: Performed docker compose down --remove-orphans, wsl --shutdown, and a full Docker "Purge Containers/WSL" to clear any networking cache.
• Direct IP Access: Attempted to access via 127.0.0.1:8081 and [::1]:8081 (8081 was just one of the manual ports I tried in the process, as 2283 is the same result), but connection is refused because the service is bound to the container's internal loopback only.

[topaz obsidian]

ChatGTP suggested try this code segment - basically hardcoded the env variable:
immich_server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:release
ports:
- "8081:2283"
env_file:
- immich.env
environment:
- IMMICH_HOST=0.0.0.0
- IMMICH_PORT=2283
volumes:
- F:/Photos_backup/Immich/upload:/usr/src/app/upload
- F:/Photos_backup/Pixel:/external/Pixel:ro
- /etc/localtime:/etc/localtime:ro
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_started

And this doesn't work either.

Lastly, I have also tried to use different browsers, incognito mode, "wsl --shutdown" to refresh the Linux subsystem, delete all Immich files and folder and redo the pulling, using "net stop winnat" and "net start winnat" to refrsh the bridge to Windows, "docker compose down --remove-orphans --volumes" and "docker image prune -a" to clear the Docker, and many Windows machine restart, etc., and none of these would fix the problem, and Immchi welcome screen will just not come up in the browser.

[craggy helm]

The AI is wrong, sorry to say
Our documentation specifically says that we do not recommend windows, so no, we don’t do much testing on windows

It can work on windows, but issues like this are common especially with networking or external drives

This does seem to be some kind of firewall related issue

Please post a screenshot of the url you are trying to reach

Uh why did you map port 8081? That’s not from our docker compose

I think you need to start over with no AI junk

[topaz obsidian]

Port 8081 was used only as a testing step in the troubleshooting, because the default port 2283 failed to connect to Windows. After Immich was running in Docker, docker ps displayed this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
2967c00521c7 ghcr.io/immich-app/immich-server:release "tini -- /bin/bash -…" About a minute ago Up 54 seconds (healthy) 2283/tcp immich_server
f9a7bec9af98 valkey/valkey:8 "docker-entrypoint.s…" About a minute ago Up About a minute (healthy) 0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp immich_redis
830af0c3277e tensorchord/pgvecto-rs:pg16-v0.2.0 "docker-entrypoint.s…" About a minute ago Up About a minute (healthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp immich_postgres
36c3a628efb9 ghcr.io/immich-app/immich-machine-learning:v2 "tini -- python -m i…" About a minute ago Up About a minute (healthy) immich_machine_learning

Noticed that for the immich_server, the PORTS column is empty (it just says 2283/tcp), meaning that this in a "Bridge Mode" but the port isn't actually being mapped from the container to Windows, and Immich in Docker isn't "plugged in" to that port. Since port 2283 on Windows host seems to be held hostage by a ghost process - possibly a previous crashed Immich connection attempt, this is just to do a test by moving the "entry gate" to a completely different port.

After tried this test code, I got the Immich server to show the right connection at 0.0.0.0:8081->2283/tcp, [::]:8081->2283/tcp
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
814dbfd2a70b ghcr.io/immich-app/immich-server:release "tini -- /bin/bash -…" 11 seconds ago Up 4 seconds (health: starting) 0.0.0.0:8081->2283/tcp, [::]:8081->2283/tcp immich_server

This shows that the 0.0.0.0:8081->2283/tcp entry in the PORTS column confirms that the "tunnel" is finally established - Port 8081 on the Windows machine is now successfully wired to the Immich server inside the container. But what exactly process in either Immich in Docker hijacked port 8081, there's no any error message, which is a poor software system design on the Immich's part, because it should at least post some error messages if it can't open a channel to connect to Windows port.

Even though this test gets the port open, the Immich still doesn't work - even docker ps is finally showing the correct port mapping and 0.0.0.0:8081 is open in Docker, but the browser still says "Connection Refused", it indicates two things are likely happening: 1. there's a ghost Listener: Windows thinks port 8081 is open, but the data isn't reaching the WSL2 engine, and/or 2, IP Bind: The Immich app inside is still stubbornly refusing to talk to anyone but to itself.

So the obvious question is: why? Does Immich code have a bug there for the port use?

But regardless, not using 8081 but the default 2283 in your template code, Immchi still doesn't come up. This also has nothing to do with firewall, as I have disabled the firewall for both Immich and Docker, and it still doesn't work - the browser still does not bring up the Immich start screen. The external drive is also not an issue, because change to an internal drive is the same result.

So the question is: what else can be done, in either troubleshooting or fix the problem with code change in the compose.yml file? - again, I am now using the exact latest template file downloaded from your GitHub page.

The screen shot for the URL http://<machine-ip-address>:2283

[craggy helm]

This is a ton of info, frankly almost none of which is Immich's fault. We don't have visibility into host OS port mapping

If you changed it to 8081:2283, you should be trying localhost:8081

anyway, I do not know anything about docker on windows, so I (and most of the team here) are probably not able to help a lot, but maybe someone will see this who has some ideas. Sorry for the trouble

[topaz obsidian]

Yes I did try localhost:8081 as well, and that doesn't work either. But again, I have revert back to your template file with the default port number, and I am not using 8081 now (that was just a test step early to see what's going on with the port mapping), and the main issue is that even with your published template file, it still doesn't work. The biggest issue is that Immich doesn't produce any useful error message, making troubleshooting very hard. I'd recommend the development team consider adding some error handling code, to spit out status code on port mapping, docker and windows connection, etc. Otherwise this is a unusable software on Windows, and you should explicitly declare so - don't just say " we don’t do much testing on windows", but rather "this software has not been fully tested on Windows, and it lacks error handling and error messages. Do not use it on Windows". I appreciate your honesty in saying that you and the team do not know much about Docker. So unless there are useful troubleshoot suggestions that can help me fix the issue, I am going to abandon using Immich, and look for alternative programs. Thanks!

[craggy helm]

Immich runs in a container, so the "running" of docker and networking, etc is delegated to the host and the administrator. THis allows us to focus on developing Immich itself

so, the app itself has basically no idea about error messages etc, as it has no insight as to anything that happens outside the host

If you want to stick on windows you would have better luck using a full VM I believe

https://docs.immich.app/install/requirements/
"Non-Linux OSes tend to provide a poor Docker experience and are strongly discouraged. Our ability to assist with setup or troubleshooting on non-Linux OSes will be severely reduced. "

For some of our users, it works fine on Windows. So, we cannot say it is guaranteed not to work, but it is strongly discouraged. If you have any suggestion to reword that phrase you could open a PR If you would like as well