Bug: Fix `surfaceError` method in the new product registration - stack trace swallowed

[aalves08]

Setup

• Rancher version: n/a
• Rancher UI Extensions: n/a
• Browser type & version: n/a

Describe the bug

We're swallowing the stack trace. So the error is good but doesn't help developers work out where in code the error is.

surfaceError method should be:

 private surfaceError(message: string, e: any): never {
    console.error(`Resource API error - ${ this.storeType } - ${ message }`); // eslint-disable-line no-console
    throw new Error(`Resource API error - ${ this.storeType } - ${ message }`, { cause: e });
  }

and we should update all usages in the new product registration API

To Reproduce

Result
as per description

Expected Result

as per description

Screenshots

Additional context

[github-actions]

🎯 Agentic Issue Triage

Summary: The surfaceError method in shell/core/plugin-products-base.ts swallows the original error's stack trace when re-throwing, making debugging much harder. The fix involves updating the method to accept the original error as a second parameter and pass it via the { cause: e } option in the Error constructor — a standard JavaScript error-chaining pattern available since Node 16 / modern browsers.

📍 Current Implementation

File: shell/core/plugin-products-base.ts (line 46–48)

// Current - stack trace is lost
protected surfaceError(message: string): void {
  throw new Error(`Extensions - product "${ this.name }" registration error ::: ${ message }`);
}

Call sites (all in plugin-products-base.ts and plugin-products-extending.ts):

• this.surfaceError('No children found for product with config') — no original error available, will need e to be optional
• this.surfaceError('Invalid child item for product default route - missing name or type')
• this.surfaceError('Children defined for group are not in an array format')
• this.surfaceError(\Duplicate page name...`)`
• this.surfaceError(\Duplicate resource type...`)`
• this.surfaceError('Group items cannot have a "type" property...')
• this.surfaceError('Custom pages cannot have a "type" property...')
• plugin-products-extending.ts: this.surfaceError(\Product "${ this.name }" is not extendable...`)`

Note: Most call sites don't currently pass a caught error, so the second parameter should be optional.

🔧 Suggested Fix

// Updated - stack trace preserved via Error cause chaining
protected surfaceError(message: string, e?: unknown): never {
  throw new Error(
    `Extensions - product "${ this.name }" registration error ::: ${ message }`,
    e ? { cause: e } : undefined
  );
}

Key changes:

1. Return type void → never (more accurate: it always throws)
2. Optional second parameter e?: unknown for the original error
3. Passes { cause: e } to Error constructor to preserve the original stack trace

No changes to the call sites are strictly required since e is optional, but callers inside try/catch blocks should be updated to pass the caught error where applicable.

✅ Sub-tasks / Checklist

• Update surfaceError signature in shell/core/plugin-products-base.ts to accept an optional e?: unknown second parameter
• Change return type from void to never
• Pass { cause: e } (when e is present) to the Error constructor
• Review all surfaceError call sites in plugin-products-base.ts and plugin-products-extending.ts — update any that are inside catch blocks to forward the caught error
• Add/update unit tests for surfaceError to assert the cause property is set on the thrown error
• Verify with TypeScript that never return type is accepted (should be fine — a method that always throws satisfies never)

🐛 Debugging Strategy

To observe the issue today:

1. Intentionally trigger a registration error (e.g., pass a config with no children to a new product)
2. Catch the thrown error in the browser DevTools console and inspect error.cause — it will be undefined
3. After the fix, error.cause will reference the original error with its full stack

📚 Resources

• [MDN: Error cause (ES2022)]((developer.mozilla.org/redacted) — the { cause } option in the Error constructor
• [TypeScript never return type]((www.typescriptlang.org/redacted) — correct return type for functions that always throw

Generated by Agentic Triage for issue #17405 · ● 247.3K · ◷