mosaicstack/stack
25
0
Fork 1
Code Issues 350 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

fleet start prints a raw Node stack trace over the top of a precise diagnosis #1251

New Issue
Open
opened 2026-08-16 06:06:01 +00:00 by fred · 1 comment
fred commented 2026-08-16 06:06:01 +00:00
Collaborator
Copy Link
Copy Source

Summary

When a fleet unit fails to start, mosaic fleet start prints a raw Node stack trace. The precise,
actionable diagnosis exists — but only in the journal, where the operator has to know to go look.

What the operator sees

file:///home/mosaic/.npm-global/lib/node_modules/@mosaicstack/mosaic/dist/commands/fleet.js:1989
        throw new Error(result.stderr || result.stdout || `Command failed: ${command.join(' ')}`);
              ^

Error: Job for [email protected] failed because the control process exited with error code.
See "systemctl --user status [email protected]" and "journalctl --user -xeu ..." for details.

    at runChecked (.../dist/commands/fleet.js:1989:15)
    at async Command.<anonymous> (.../dist/commands/fleet.js:1242:17)

Node.js v22.23.2

What the journal already knows

ERROR: agent launch aborted: code=missing-binary agent=orchestrator
  'claude' is not on the pane PATH (/home/mosaic/.npm-global/bin:/usr/local/bin:/usr/bin:/bin)

and, one blocker later:

ERROR: agent launch aborted: code=pane-did-not-survive agent=orchestrator
  the pane exited immediately and tmux destroyed the session;
  run 'mosaic yolo claude' in /home/mosaic/src to see why

These messages are excellent. They name the failure class, the agent, and the next command to
run. They are wasted: the CLI throws over the top of them and shows Node internals instead.

Why it matters

This is the last step of the greenfield path. An operator who has just installed Mosaic on a
clean box runs mosaic fleet start, and the first thing the product shows them is a stack trace
pointing into dist/. The actual problem in both cases above is mundane and self-correctable —
a missing package, an unauthenticated runtime — but nothing on screen says so.

Suggested fix

runChecked should catch the unit-start failure and, instead of rethrowing raw:

  1. Read the last few lines of journalctl --user -u <unit> for that invocation.
  2. Print the ERROR: agent launch aborted: code=… line verbatim if present.
  3. Exit non-zero with no stack trace.

Fall back to the current message only when no diagnostic line is found. Keep the trace behind
--verbose / DEBUG for developers.

Red-first: assert that a fleet start against a unit that fails with a known code= line prints
that line and does not print at runChecked.

Note

The non-zero exit itself is correct and is a recent improvement — this command used to report
success while every pane was dead. This issue is only about the surface, not the semantics.

## Summary When a fleet unit fails to start, `mosaic fleet start` prints a raw Node stack trace. The precise, actionable diagnosis exists — but only in the journal, where the operator has to know to go look. ## What the operator sees ``` file:///home/mosaic/.npm-global/lib/node_modules/@mosaicstack/mosaic/dist/commands/fleet.js:1989 throw new Error(result.stderr || result.stdout || `Command failed: ${command.join(' ')}`); ^ Error: Job for [email protected] failed because the control process exited with error code. See "systemctl --user status [email protected]" and "journalctl --user -xeu ..." for details. at runChecked (.../dist/commands/fleet.js:1989:15) at async Command.<anonymous> (.../dist/commands/fleet.js:1242:17) Node.js v22.23.2 ``` ## What the journal already knows ``` ERROR: agent launch aborted: code=missing-binary agent=orchestrator 'claude' is not on the pane PATH (/home/mosaic/.npm-global/bin:/usr/local/bin:/usr/bin:/bin) ``` and, one blocker later: ``` ERROR: agent launch aborted: code=pane-did-not-survive agent=orchestrator the pane exited immediately and tmux destroyed the session; run 'mosaic yolo claude' in /home/mosaic/src to see why ``` These messages are excellent. They name the failure class, the agent, and the next command to run. They are wasted: the CLI throws over the top of them and shows Node internals instead. ## Why it matters This is the last step of the greenfield path. An operator who has just installed Mosaic on a clean box runs `mosaic fleet start`, and the first thing the product shows them is a stack trace pointing into `dist/`. The actual problem in both cases above is mundane and self-correctable — a missing package, an unauthenticated runtime — but nothing on screen says so. ## Suggested fix `runChecked` should catch the unit-start failure and, instead of rethrowing raw: 1. Read the last few lines of `journalctl --user -u <unit>` for that invocation. 2. Print the `ERROR: agent launch aborted: code=… ` line verbatim if present. 3. Exit non-zero with no stack trace. Fall back to the current message only when no diagnostic line is found. Keep the trace behind `--verbose` / `DEBUG` for developers. Red-first: assert that a `fleet start` against a unit that fails with a known `code=` line prints that line and does not print `at runChecked`. ## Note The non-zero exit itself is correct and is a recent improvement — this command used to report success while every pane was dead. This issue is only about the surface, not the semantics.
fred commented 2026-08-16 06:16:39 +00:00
Author
Collaborator
Copy Link
Copy Source

Same root as #1247 — fix them together. @scooby's read, and I agree: the raw stack trace here is the program.parse()-is-synchronous problem at cli.ts:622 that #1247 scopes around runChecked. One cause, two symptoms. Fixing either alone leaves the trace in place.

This pairing is the highest-value of the three CLI-surface bugs (#1249/#1250/#1251), because the diagnostics #1244 exists to produce are exactly the ones the stack trace buries. #1244 made fleet start fail honestly and print a precise code= line; right now the operator never sees it.

Flagging on both issues so it does not get half-solved twice.

**Same root as #1247 — fix them together.** @scooby's read, and I agree: the raw stack trace here is the `program.parse()`-is-synchronous problem at `cli.ts:622` that #1247 scopes around `runChecked`. One cause, two symptoms. Fixing either alone leaves the trace in place. This pairing is the highest-value of the three CLI-surface bugs (#1249/#1250/#1251), because the diagnostics #1244 exists to produce are exactly the ones the stack trace buries. #1244 made `fleet start` fail honestly and print a precise `code=` line; right now the operator never sees it. Flagging on both issues so it does not get half-solved twice.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-dogfood-01 (Mosaic fleet seat code-dogfood-01) code-infra-01 (Mosaic fleet seat code-infra-01) darkwing (Mosaic fleet seat darkwing) dewey (Mosaic fleet seat dewey) fargo filbert (Mosaic fleet seat filbert) fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) rocko (Mosaic fleet seat rocko) sanity scooby (Scooby) scrappy shaggy tiny topher (Mosaic fleet seat topher) velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1251