Say why the server will not start, and where to report it #1067

Merged
jaylouisw merged 1 commit from fix/server-will-not-start into main 2026-11-08 15:17:01 +00:00
Owner

The most common reason PacketForge does not start is that a port is already taken. Until now that reached the user as a raw EADDRINUSE stack trace — at the one moment the web UI, and with it the Report a bug button added in #1065, does not exist.

server/startup-error.js turns the failures a normal person actually hits into sentences:

errno what they now read
EADDRINUSE the port is named, the likely cause ("a PacketForge still running in another terminal"), and three shell-specific ways to pick another one
EACCES ports below 1024 need privilege, here is where the boundary is
anything else the original message, kept intact, plus the report link

Self-inflicted failures (EACCES, EADDRNOTAVAIL) deliberately do not invite a bug report — sending someone to open an issue because they typed PORT=80 wastes their time and ours.

Why the message and not the button

The reporting path has to work in exactly the case where the UI is absent. So the report link is a prefilled issues/new URL carrying a template that asks for the terminal output and how they started it, and the message prints it.

Tests

test/startup-error.test.js, 25 checks, in two halves:

  • unit — the wording per errno, that a known remedy is offered, that a null error still yields a sentence, that undefined never reaches the output.
  • integration — starts two real servers on one port and reads what the loser prints: exit code 1, the sentence, the fix, the report link, and no stack trace. A message builder that is never wired up is still dead code; this half holds the wiring.

Local: node scripts/syntax-check.js 164 files OK · node test/startup-error.test.js 25/25.

Unrelated, pre-existing failure on main

While running the suite I found test/mikrotik-naming.test.js red on main from #776 — the RDS2216 declares SFP+281..283 with sfp28 media and lowercase qsfp281. That is a separate device-data bug and gets its own PR, not this one.

The most common reason PacketForge does not start is that a port is already taken. Until now that reached the user as a raw `EADDRINUSE` stack trace — at the one moment the web UI, and with it the **Report a bug** button added in #1065, does not exist. `server/startup-error.js` turns the failures a normal person actually hits into sentences: | errno | what they now read | |---|---| | `EADDRINUSE` | the port is named, the likely cause ("a PacketForge still running in another terminal"), and three shell-specific ways to pick another one | | `EACCES` | ports below 1024 need privilege, here is where the boundary is | | anything else | the original message, kept intact, plus the report link | Self-inflicted failures (`EACCES`, `EADDRNOTAVAIL`) deliberately **do not** invite a bug report — sending someone to open an issue because they typed `PORT=80` wastes their time and ours. ### Why the message and not the button The reporting path has to work in exactly the case where the UI is absent. So the report link is a prefilled `issues/new` URL carrying a template that asks for the terminal output and how they started it, and the message prints it. ### Tests `test/startup-error.test.js`, 25 checks, in two halves: - **unit** — the wording per errno, that a known remedy is offered, that a null error still yields a sentence, that `undefined` never reaches the output. - **integration** — starts two real servers on one port and reads what the loser prints: exit code 1, the sentence, the fix, the report link, **and no stack trace**. A message builder that is never wired up is still dead code; this half holds the wiring. Local: `node scripts/syntax-check.js` 164 files OK · `node test/startup-error.test.js` 25/25. ### Unrelated, pre-existing failure on main While running the suite I found `test/mikrotik-naming.test.js` red on `main` from #776 — the RDS2216 declares `SFP+281..283` with `sfp28` media and lowercase `qsfp281`. That is a separate device-data bug and gets its own PR, not this one.
Say why the server will not start, and where to report it
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m32s
CI / Test (Node 20) (pull_request) Failing after 1m25s
CI / Server smoke test (pull_request) Successful in 26s
CI / Docker build (pull_request) Successful in 11s
CI / Test (Node 22) (pull_request) Failing after 1m25s
0fc2be39d9
The most common reason PacketForge does not start is that a port is already
taken, and until now that reached the user as a raw EADDRINUSE stack trace. The
stack trace never mentions the remedy, and it is printed at the one moment the web
UI - and with it the Report a bug button added in #1065 - does not exist.

server/startup-error.js turns the two failures a normal person actually hits into
sentences: a port in use names the port, the likely cause and the three
shell-specific ways to pick another one; a privileged port says where the 1024
boundary is. Anything unrecognised keeps its original message and gains the report
link. Self-inflicted failures (EACCES, EADDRNOTAVAIL) deliberately do not invite a
bug report.

test/startup-error.test.js checks the wording, then starts two real servers on one
port and reads what the loser prints: exit code 1, the sentence, the fix, the
report link, and no stack trace.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-08 14:56:35 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1067
No description provided.