feat(cli): add crash reporting with trace ids by matthewvolk · Pull Request #2880 · bigcommerce/catalyst

matthewvolk · 2026-02-13T00:48:08Z

What/Why?

When the CLI crashes, customers send screenshots to support which aren't actionable. This PR instruments the CLI so that on any error, a trace ID (UUID) is displayed. The customer shares it with support, who can look up the session across telemetry systems.

This works because every outgoing BigCommerce API request now includes an X-Correlation-Id header set to the trace ID.

Changes

Centralized error handling

New withErrorHandler() HOF that wraps Commander .action() callbacks
On error: tracks via telemetry, displays trace ID, exits with code 1
Removes duplicated try/catch + consola.error + process.exit(1) from all 6 command actions (deploy, build, dev, start, project list/create/link)

Telemetry singleton

getTelemetry() / resetTelemetry() singleton pattern replaces per-module new Telemetry() instances
sessionId changed from randomBytes(32).toString('hex') to randomUUID() for a human-readable, support-friendly format
New traceId(), durationMs(), and trackError() methods
All track() calls enriched with traceId, nodeVersion, platform, arch, cliVersion

API correlation

X-Correlation-Id header added to all 6 BigCommerce API fetch calls (4 in deploy.ts, 2 in project.ts)

Global safety net

uncaughtException and unhandledRejection handlers in index.ts

User-facing output on crash:

Error: Failed to fetch upload signature: 401 Unauthorized

Trace ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Share this Trace ID with BigCommerce support.

Testing

67 tests passing across 13 test files
New test suites for error-handler.spec.ts and telemetry.spec.ts
Updated assertions in deploy.spec.ts and project.spec.ts
Lint passes with 0 errors/warnings

Migration

N/A — no breaking changes to public API or file structure.

Centralized error handling via withErrorHandler HOF, singleton telemetry with UUID trace ids, X-Correlation-Id headers on all API calls, and global uncaught exception handlers. On any CLI error, a trace ID is displayed for support debugging.

changeset-bot · 2026-02-13T00:48:13Z

⚠️ No Changeset found

Latest commit: d9d52a4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2026-02-13T00:48:13Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Feb 13, 2026 4:41pm

chanceaclark

I feel like a lot of this PR can be simplified. Let's work together tomorrow to trim it down.

chanceaclark · 2026-02-13T01:28:03Z

.changeset/brave-tigers-trace.md

You can omit the changeset here

chanceaclark · 2026-02-13T01:30:06Z

packages/catalyst/src/cli/lib/telemetry.ts

      properties: {
        ...payload,
        sessionId: this.sessionId,
+        traceId: this.traceId(),


Trace id and session id above are the same thing. Can we just normalize this all to use session id internally but show it as trace id externally?

chanceaclark · 2026-02-13T01:34:37Z

packages/catalyst/src/cli/hooks/telemetry.ts

@@ -46,5 +45,8 @@ export const telemetryPreHook = async (command: Command) => {
 };

 export const telemetryPostHook = async () => {


Are there arguments on this that we can determine if the command failed with an error? It would be cleaner than having to add a closure around each command and is more scalable.

Ok I was actually just playing around with this in a sandbox and here's what I found:

const { Command } = require('commander'); const p = new Command(); p.command('test').action(async () => { throw new Error('boom'); }); p.hook('postAction', () => { console.log('POST_ACTION_FIRED'); }); p.parseAsync(['node', 'test', 'test']).catch(e => console.log('CAUGHT:', e.message));

If you run that, you don't see POST_ACTION_FIRED. I guess hooks in Commander work like .then()?

TL;DR... to your original question, I don't think so... but open to your thoughts

chanceaclark · 2026-02-13T01:36:55Z

packages/catalyst/src/cli/lib/telemetry.ts

    });
  }

+  async trackError(commandName: string, error: unknown) {


Do we need to add a whole new function if we are only calling it once? Can we just use the existing track function?

I'll combine 👍

chanceaclark · 2026-02-13T01:37:19Z

packages/catalyst/src/cli/lib/telemetry.ts

  }
 }
+
+let telemetryInstance: Telemetry | undefined;


Can you explain why we need a singleton here?

Right now it's because the pre-hook, post-hook, error handler, and command action callback (for X-Correlation-Id) all call getTelemetry() independently — without the singleton they'd each get a fresh sessionId... though after I incorporate your feedback to leverage the postHook more, maybe this changes

Actually, see #2880 (comment)

I think a fresh session per command call is expected? As in you call the CLI once, you get a new session, then call it again it's a separate session.

matthewvolk · 2026-02-13T16:37:10Z

@chanceaclark just updated, let me know what you think 👍

matthewvolk requested a review from a team as a code owner February 13, 2026 00:48

vercel bot deployed to Preview February 13, 2026 00:49 View deployment

chanceaclark reviewed Feb 13, 2026

View reviewed changes

matthewvolk requested a review from chanceaclark February 13, 2026 16:37

vercel bot deployed to Preview February 13, 2026 16:38 View deployment

refactor(cli): remove traceId() and trackError() abstractions

d9d52a4

matthewvolk force-pushed the CATALYST-1725-tracing branch from eb7d627 to d9d52a4 Compare February 13, 2026 16:39

vercel bot deployed to Preview February 13, 2026 16:41 View deployment

		@@ -46,5 +45,8 @@ export const telemetryPreHook = async (command: Command) => {
		};

		export const telemetryPostHook = async () => {

Conversation

matthewvolk commented Feb 13, 2026

What/Why?

Changes

Testing

Migration

Uh oh!

changeset-bot bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chanceaclark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewvolk commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Feb 13, 2026 •

edited

Loading

vercel bot commented Feb 13, 2026 •

edited

Loading