[Bug]: Another program is using port 8000

[grendelmintcake]

Before reporting

• I'm on the latest release and the issue still happens.
• I searched existing issues and didn't find a duplicate.

What happened?

When I attempt to run the windows install (no NVIDIA GPU), I get this error on the last box, start backend, it says:

Another program is already using port 8000

I don't have any other applications running, any ideas how I can fault find?

Steps to reproduce

1. Open StemDeck-Windows-x64
2. Runs through setups steps fine until the last step

Operating system

Windows

StemDeck version

StemDeck Windows Portable Alpha

How did you install it?

Windows ZIP

Logs / screenshots

backend did not become healthy within 90 seconds.

Another program is already using port 8000 (process 16452). If that is a second copy of StemDeck, close it and try again, or change the port in Settings.

Last backend log lines from [WINDOWS LOCATION]\backend.log:
INFO: 127.0.0.1:11325 - "GET /api/health HTTP/1.1" 200 OK

[nhorne]

I am seeing the same thing with the Nvidia release. The PID that the log says is already using port 8000 belongs to a Python process started by that same instance of StemDeck.

[diegoarusso]

I can reproduce this on the Windows x64 CPU-only portable build, and I captured
the process tree and the health payload. This does not appear to be another
program using port 8000.

The process tree during one clean launch was:

StemDeck.exe   9172   parent 6924
python.exe    17800   parent 9172
python.exe    11584   parent 17800

The backend was healthy and continuously returned HTTP 200 from
GET /api/health, but its payload contained:

{"name":"StemDeck","status":"ok","version":"0.15.1","pid":11584}

The desktop shell appears to retain the PID of the direct child it spawned
(17800), while the process actually serving the API is that child's child
(11584). The health endpoint correctly reports os.getpid(), so the shell
compares 11584 with 17800, treats its own backend as a foreign process on
the port, polls until the 90-second timeout, and shows the misleading
"Another program is already using port 8000" message.

This matches the intent documented around app/main.py's /api/health
endpoint: the PID was added so the shell would not adopt another StemDeck
instance's backend (#424). On this Windows portable runtime there are two
Python process layers, so comparing only against the initially spawned PID
rejects the legitimate grandchild.

Additional observations:

• The failure is deterministic and survived a full Windows restart.
• Ports 8000 and 8010 were confirmed free before launch.
• The health log contains repeated HTTP 200 responses; reachability is not the
  problem.
• Starting the bundled backend interpreter manually works, which further
  isolates this to desktop-shell child identity/health validation rather than
  FastAPI startup.
• This also reproduces for another user in this thread on the NVIDIA build, so
  it likely is not specific to the CPU package.

Environment: Windows 11, StemDeck 0.15.1, Windows x64 CPU-only portable build,
Intel i5-8350U / 16 GB.

I have reverted to 0.13.0 for now. I can provide a fuller process dump if useful.

[thcp]

You were both right, and the diagnosis in this thread was correct: nothing else is using port 8000. The process the shell was calling a foreign program is StemDeck's own backend.

@diegoarusso, that process tree is what settled it. Thank you for capturing it.

Here is what was happening. The desktop shell checks that the process answering /api/health is the one it just started, so a second copy of StemDeck cannot quietly take over the first copy's library. It did that by comparing process IDs. That assumes the process holding the port is the process it spawned.

On the Windows portable build it is not. python\Scripts\python.exe is a small venv launcher that points at python\base\python.exe, and Windows has no way to replace a running process, so the launcher starts the real interpreter underneath itself. The interpreter that binds the port is a grandchild. Its process ID could never match, which is the middle and bottom rows of your tree.

So the shell waited the full ninety seconds on a backend that was healthy the whole time, then reported the one process ID it had seen as the intruder. Linux and macOS were never affected, because there is no launcher in front of the interpreter there.

The fix is in #460. Identity now travels in the environment, which survives that re-exec: the shell hands the backend a token at startup and the backend echoes it back. I reproduced the failure on a local build and confirmed the same package starts normally with the fix, so this is verified on a real build rather than in review.

It will ship in 0.15.2. Windows and Linux installs will get it through the in-app updater, no reinstall needed.

I am sorry for the trouble this caused. Being unable to open the app at all, with an error pointing at a program that does not exist, is a bad first experience and it cost you real time working out that it was not your machine.

I will comment here again when 0.15.2 is out.

[thcp]

0.15.2 is out with the fix, and it is confirmed working on Windows.

https://github.com/stemdeckapp/stemdeck/releases/tag/v0.15.2

If you are one of the people this stopped, take the full download rather than looking for the in-app updater. The updater lives in the part of the app you were never able to reach.

• Windows, no NVIDIA GPU: StemDeck-Windows-x64.zip
• Windows, NVIDIA GPU: StemDeck-Windows-x64.NVIDIA.zip

Unzip it over a fresh folder and run StemDeck.exe. Your library and settings live outside the package, so they carry over.

@grendelmintcake, @nhorne, @diegoarusso, thank you for staying with this. You had it right from the first report: nothing else was using the port. The process trees in this thread are what made the cause obvious, and that turned it from a puzzle into a small change.

Sorry again for the time it cost you. If anything is still off after updating, reopen this or open a new issue and I will take a look.