Why?

Because of the way the internals of the SDK's async HTTP calling code are structured, when we throw an error, it loses its original stack trace. Users have only been able to trace issues back to where our HTTP calls originate from, not where in their code caused the HTTP call that failed.

The best solution is to use promises all the way down our HTTP chain, which will let node resolve stack traces as we'd expect. But that's a pretty big internal change and is part of why the team hadn't prioritized it in the past.

We talked it over this week and decided to take a more tactical approach: by manually instantiating an unthrown error before doing any async operations, we can reference its call stack if the async operation later fails. That gives us pretty usable tracebacks (seen below). I've also manually confirmed that it works for autoPagingEach and autoPagingToArray.

As far as I can tell, we didn't try this before because of perceived performance implications, but based on local testing with real API calls, the difference is negligible (approx. 30ms / request, which is indistinguishable from network jitter). We'll still probably go through and simplify this code in the future, but this is a reasonable stopgap until we get to that.

before:

Error: Invalid API Key provided: sk_test_fake
    at generateV1Error (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/Error.ts:27:12)
    at <anonymous> (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/RequestSender.ts:194:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)

after:

Error: Invalid API Key provided: sk_test_fake
    at generateV1Error (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/Error.ts:27:12)
    at <anonymous> (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/RequestSender.ts:194:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
Originating from:
    at CustomerResource._makeRequest (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/StripeResource.ts:97:27)
    at CustomerResource.list (/Users/xavdid/stripe/hello-sdks/node/node_modules/stripe/src/resources/Customers.ts:207:17)
    at listCustomers (/Users/xavdid/stripe/hello-sdks/node/index.ts:9:52)
    at <anonymous> (/Users/xavdid/stripe/hello-sdks/node/index.ts:20:7)
    at ModuleJob.run (node:internal/modules/esm/module_job:430:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:661:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

What?

• manually capture tracebacks before performing async operations. Then, bind that stack to the error if one is thrown (in 3 places)
• tests

See Also

• Use async functions within request handling code #1542
• Errors miss useful stack traces #1707
• Missing stack trace on errors #1066
• DEVSDK-1103