Windows: FloCafe fails to start when ports 3001 and 3002 are occupied

[ADITYA-tp01]

Bug description

FloCafe fails to start on Windows when ports 3001 and 3002 are already occupied by another process.

In my case, the ports were occupied by a Docker container running in the background from another project.

The startup output showed:

[kill-ports] Port 3001 is not free.
[kill-ports] Port 3002 is not free.

Instead of starting on the next available port, such as 3003, FloCafe failed to start.

Steps to reproduce

1. Run FloCafe in the Windows development environment using npm run dev.
2. Start another application or Docker container that occupies ports 3001 and 3002.
3. Start FloCafe.
4. Observe the startup output.
5. FloCafe fails to start instead of switching to the next available port, such as 3003.

Expected behavior

FloCafe should detect that ports 3001 and 3002 are already occupied and automatically start on the next available port (3003`) instead of failing to start.

Actual behavior

FloCafe fails to start when ports 3001 and 3002 are already occupied.

The startup output shows:

[kill-ports] Port 3001 is not free.
[kill-ports] Port 3002 is not free.

Instead of switching to an available port such as 3003, the application fails to start.

Operating System

Windows

Installation Method

GitHub / direct installer

FloCafe version

3.3.1 - beta 3

OS version & architecture (optional)

Windows 11 64-bit

Relevant logs or printer output

No response

Screenshots & hardware context

No response

[khaira777]

Thanks for reporting this!

Root Cause & How Port Handling Works in FloCafe

1. kill-ports.js allowlist behavior:
   When running npm run dev, kill-ports.js runs first as a dev-cleanup step. It inspects process command lines and intentionally skips non-Flo processes (such as Docker containers or database daemons) so it never terminates third-party software on your system. The log line SKIP — PID ... is not a Flo process indicates that the port was left untouched for Docker.

2. Automatic port fallback in FloCafe:
   During startup, FloCafe's servers (Main API on 3001, KDS Server on 3002, and Server App on 3003) catch EADDRINUSE errors and automatically increment to the next available port (up to 10 attempts each).

   • When ports 3001 and 3002 are held by Docker, Main API binds to 3003, KDS binds to 3004, and Server App binds to 3005.
   • In the packaged desktop app, Electron dynamically queries getServerPort() and loads the shifted port seamlessly.

3. Development workflows with Docker / non-Flo services:
   If you have Docker or another service permanently holding default ports 3001/3002, you can set custom base ports in your .env file to avoid collisions:

   PORT=4001
   KDS_PORT=4002
   SERVER_APP_PORT=4003

Updates Added

We have added clearer notices in kill-ports.js, dev-server.js, .env.example, and CONTRIBUTING.md so that when a non-Flo process is detected holding a default port, the CLI outputs a clear tip explaining the automatic port increment behavior and how to set custom ports in .env.