Services built to fail
One TypeScript server runs every service of this project in a different MODE, and all but one are broken on purpose. Each one, started by name, shows what devlanes prints in devlanes start, devlanes debug why and the proxy’s error pages (DL101 to DL303).
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22 or later
Run it
Section titled “Run it”cd showcase-brokendevlanes startdevlanes start --no-ui --output plain prints the start as text:
ok installexample-broken@0 · mainok services 1 of 1 ready ok index https://example-broken.localhostOpen https://example-broken.localhost. The page says This is lane 0 of example-broken. and lists every broken service with the error it causes, its hostname and the command that starts it.
During a start
Section titled “During a start”- The first start of a lane runs the
installtask (npm install). - The
defaultprofile names onlyindex, so a plain start runs that one service (npm run dev, which istsx watch src/index.tswithMODE=index) and waits for/healthz. - The other services have hostnames from the start: until one is started, its hostname answers DL201.
Every broken service extends the broken template, which runs npm run serve (tsx src/index.ts without watch, so a crash ends the process) and tags it broken, so +broken selects them all.
A plain devlanes start brings back what the lane ran before, broken services included. devlanes stop without names forgets them, and the next plain start runs only index again.
Try next
Section titled “Try next”The output below was captured with --output plain and trimmed. On Windows, add --ssl-revoke-best-effort to the curl commands.
Crash on boot
Section titled “Crash on boot”crash-on-boot prints a message and exits 1 before it listens:
devlanes start crash-on-boot --no-uiexample-broken@0 · mainfailed services 0 of 1 ready failed crash-on-boot exited 1 crash-on-boot: ACME_API_KEY is not set, refusing to boot
logs: devlanes logs example-broken@0:crash-on-boot --tail 200The unit stays failed: devlanes does not restart it, and devlanes status still shows failed=crash-on-boot later. devlanes debug errors lists it with its crash count, and devlanes debug why crash-on-boot gives the reason:
failed example-broken@0:crash-on-boot exited with code 1 (devlanes logs example-broken@0:crash-on-boot --tail 200) not selected by profile default (devlanes start example-broken@0:crash-on-boot)curl https://crash-on-boot.example-broken.localhost/ gets the DL203 page with the end of the output:
# DL203 Service failed
`service-failed`, 503 Service Unavailable, error. Sent by the devlanes 0.11.3 proxy, not by the service.
The service exited or its ready check failed.
Recent output:
```
> serve> tsx src/index.ts
crash-on-boot: ACME_API_KEY is not set, refusing to boot```
## Diagnose
- Show the cause and a fix: `devlanes debug why example-broken@0:crash-on-boot`- Read its output since the last start: `devlanes logs example-broken@0:crash-on-boot --since start`- Restart it: `devlanes restart example-broken@0:crash-on-boot`Crash on request
Section titled “Crash on request”crash-route starts healthy. /crash answers, then throws a second later:
devlanes start crash-route --no-uicurl https://crash-route.example-broken.localhost/crashcurl https://crash-route.example-broken.localhost/crash-route exits in 1 secondThe second request gets DL203 with the stack trace under “Recent output”, ending in Error: crash requested through /crash and Node.js v24.16.0, and devlanes status shows failed=crash-route. devlanes restart crash-route --no-ui brings it back.
Reset and 101
Section titled “Reset and 101”reset closes the connection to / without an answer, and upgrade answers a plain GET with 101 Switching Protocols. Both pass their ready check, since /healthz behaves:
devlanes start reset upgrade --no-uicurl https://reset.example-broken.localhost/curl https://upgrade.example-broken.localhost/# DL302 Upstream request failed
`upstream-failed`, 502 Bad Gateway, error. Sent by the devlanes 0.11.3 proxy, not by the service.
The service closed the connection or sent an invalid HTTP/1.1 response.# DL303 Unexpected protocol upgrade
`unexpected-upgrade`, 502 Bad Gateway, error. Sent by the devlanes 0.11.3 proxy, not by the service.
The service answered 101 Switching Protocols to a request that did not ask for an upgrade.Both processes keep running, and devlanes logs reset shows /: destroying the socket without an answer.
Stopped service
Section titled “Stopped service”devlanes stop resetcurl https://reset.example-broken.localhost/# DL201 Service not running
`service-idle`, 503 Service Unavailable, info. Sent by the devlanes 0.11.3 proxy, not by the service.
The service behind this hostname is stopped.
## Diagnose
- Start the whole lane: `devlanes start --lane example-broken@0`- Start the service: `devlanes start example-broken@0:reset`- Show why it is not running: `devlanes debug why example-broken@0:reset`A service that was never started gets the same page. A failed one keeps its DL203 page: devlanes stop crash-route answers nothing was running.
Missing program
Section titled “Missing program”missing-program runs acme-dev-server, which is not installed. Its run is a list, so no shell is involved and devlanes reports the spawn failure itself:
devlanes start missing-program --no-uiexample-broken@0 · main failed missing-program couldn't start: acme-dev-server: command not found on PATH
hint: check the lane's PATH: devlanes env show missing-program --lane example-broken@0devlanes logs missing-program has the same line with the PATH that was searched. The process never ran, so devlanes status lists missing-program as idle and its hostname answers DL201.
Wrong port
Section titled “Wrong port”wrong-port ignores PORT and lets the OS pick a port. With ready: started the start passes anyway:
devlanes start wrong-port --no-uicurl https://wrong-port.example-broken.localhost/# DL301 Service not listening
`upstream-unreachable`, 503 Service Unavailable, error. Sent by the devlanes 0.11.3 proxy, not by the service.
devlanes has the service as running, but nothing accepted connections on its port while the proxy retried.The page took about 8 seconds of retries. devlanes debug why wrong-port finds nothing wrong (no blocking reason found), since the unit is ready. Comparing devlanes url ls with devlanes logs wrong-port shows the mistake:
ready wrong-port.example-broken.localhost -> example-broken@0:wrong-port port=20618wrong-port#5 wrong-port listening on http://127.0.0.1:58106Ready check that never passes
Section titled “Ready check that never passes”never-ready listens on PORT, but its /healthz answers 503. Its ready timeout is 45 seconds, longer than the 30 seconds the proxy holds a request. Start it with a short --timeout so the command returns while the service is still starting:
devlanes start never-ready --no-ui --timeout 5scurl https://never-ready.example-broken.localhost/example-broken@0 · mainfailed services 0 of 1 ready starting never-readytimed out before every unit was readycurl waits 30 seconds, then gets:
# DL202 Service starting
`service-starting`, 503 Service Unavailable, warning. Sent by the devlanes 0.11.3 proxy, not by the service.
The proxy held the request while the service started, but its ready check did not pass in time. Reload when it is ready.devlanes wait never-ready exits 1 when the 45 seconds run out:
failed example-broken@0:never-ready wasn't ready in time; GET /healthz (Host: 127.0.0.1:20614) answered 503 | never-ready listening on http://127.0.0.1:20614 more: devlanes logs example-broken@0:never-ready --tail 200From then on the hostname answers DL203. The process keeps running, and devlanes debug why never-ready suggests a fix:
failed example-broken@0:never-ready did not become ready before the timeout; GET /healthz (Host: 127.0.0.1:20614) answered 503 (use a `ready.http.path` that answers 2xx, set `ready.http.host` if the app routes by hostname, or set `ready.http.status: 503`)Proxy loop
Section titled “Proxy loop”proxy-loop forwards each request to its own public_url and keeps the Host header, as a dev server proxy without changeOrigin does:
devlanes start proxy-loop --no-uicurl https://proxy-loop.example-broken.localhost/# DL104 Proxy loop
`proxy-loop`, 508 Loop Detected, error. Sent by the devlanes 0.11.3 proxy, not by the service.
This request already passed through this route. A dev server proxy probably sent it back to devlanes with the original Host header.Unknown hostname
Section titled “Unknown hostname”The proxy has no certificate for an unknown hostname, so HTTPS fails in the TLS handshake (curl exit 35 on Windows). Use http://:
curl http://nothing.example-broken.localhost/# DL101 Unknown host
`unknown-host`, 404 Not Found, error. Sent by the devlanes 0.11.3 proxy, not by the service.
No lane routes this hostname. While the daemon runs, it answers every request to this machine's HTTP and HTTPS ports, including requests meant for other servers.
Did you mean `reset.example-broken.localhost` (example-broken@0)?The page then lists the hostnames this machine routes.
Config typo
Section titled “Config typo”devlanes.broken.yaml is a second project file with hots instead of hosts:
devlanes --file devlanes.broken.yaml config checkerror: ...\showcase-broken\devlanes.broken.yaml is invalid at line 10, column 11: services.web.hots: unknown key `hots`; did you mean `hosts`?hint: edit ...\showcase-broken\devlanes.broken.yaml at line 10, then run this againThe check exits 1 and does not register the file’s project: devlanes lane ls -p example-broken-config answers error: example-broken-config not found afterwards.
A second lane
Section titled “A second lane”git worktree add ../examples-checkout -b feat/checkout, then cd ../examples-checkout/showcase-broken && devlanes start. The new worktree is lane 1, and https://example-broken1.localhost says This is lane 1 of example-broken. with another lane colour. devlanes start crash-on-boot --no-ui there fails only lane 1’s crash-on-boot, whose page names example-broken@1:crash-on-boot, while lane 0 keeps running.
To get lane 1 without a worktree, run devlanes lane new --name example-broken-review --start --no-ui in this folder and use devlanes --lane example-broken-review start crash-on-boot --no-ui.
When you are done, devlanes lane clean 0 --yes removes lane 0. Run it with 1 for the second lane.
devlanes.yaml: the healthyindex, thebrokentemplate, one service per failure and thedefaultprofile.devlanes.broken.yaml: a project file with a typo, forconfig check.src/index.ts: readsMODEand runs one module fromsrc/modes/.src/modes/: one small module per mode.src/failures.ts: the table the index page lists.