Better debugging for JS Compute apps: Stack traces and intermediate files in JavaScript SDK 3.37

harmony7 · December 15, 2025, 8:12am

If you’ve been building on Fastly Compute with JavaScript, you know the power of writing edge logic in a familiar web-style environment — but debugging hasn’t always been as smooth as it could be. When something throws an error in your handler, you might see just the name of the error, and even if you did get a stack trace, the line numbers often didn’t match anything in your actual source files.

Error while running request handler: foo
Stack:
  handler/result<@fastly:app.js:23:11
  buildResult@fastly:app.js:18:13
  handler@fastly:app.js:22:24
  @fastly:app.js:16:48

Example of error thrown without useful stack info

With the release of Fastly Compute JavaScript SDK 3.37, that changes. This version introduces source-mapped stack traces and an option to dump intermediate build files, making it meaningfully easier to diagnose and fix issues in your application.

What’s new

Stack tracing (--enable-stack-traces)
When you enable this flag during your build, runtime errors will now include file/line/column numbers mapped back to your original source, surviving even through other bundlers and TypeScript.
```
Unhandled error while running request handler
TypeError: foo
  at (anonymous function) (src/index.ts:10:11)
      7 | 
      8 | async function handler(_e: FetchEvent) {
      9 |   const result = await buildResult(() => {
>    10 |     throw new TypeError('foo');
                    ^
     11 |   });
     12 |   result.headers.set('content-type', 'text/plain');
     13 |   return result;
  at buildResult (src/index.ts:4:13)
  at handler (src/index.ts:9:24)
  at src/index.ts:1:46
```
Example of useful stack info and code excerpt, enabled by --enable-stack-traces

Note: Enabling stack traces implicitly includes a copy of your sources in your Wasm package. This is what allows the stack trace to show helpful nearby code, but it also means your pre-compilation source files are uploaded to Fastly’s servers.
If you do not want to include your source in the deployed Wasm, you should also pass --exclude-sources for your production builds.
Source exclusion (--exclude-sources)
Use this if you want stack tracing but prefer not to embed your raw sources. You’ll still get mapped line numbers, but without a code excerpt.
Intermediate file output (--debug-intermediate-files <dir>)
When compiling your source code, the JavaScript SDK runs a few passes of processing on it.
With this flag, you can dump these intermediate artifacts into a directory of your choice: the bundled JS, transformed code, and the final form that gets compiled into Wasm. It’s useful when debugging build-pipeline behavior or verifying exactly what the runtime is seeing.

If you’re curious about how this feature was implemented, the full discussion and code are here:

github.com/fastly/js-compute-runtime

Stack tracing / debug dump of intermediate files

main ← kats/stack-tracing

opened 07:44AM - 14 Nov 25 UTC

harmony7

+786 -92

This PR adds two features to the JS Compute Runtime, both using just JavaScript …means (rather than by modifying the C++). ## Stack tracing (`--enable-stack-traces`) Consider the following example code. ```typescript addEventListener('fetch', e => e.respondWith(handler(e))); async function buildResult(fn: () => number): Promise<Response> { const x = fn(); return new Response(String(x)); } async function handler(_e: FetchEvent) { const result = await buildResult(() => { throw new TypeError('foo'); }); result.headers.set('content-type', 'text/plain'); return result; } ``` By enabling the new option, the above code can be made to return an error stack like this: ``` 2025-11-14T07:01:15.535095Z INFO request{id=0}: handling request GET http://localhost:7676/ Unhandled error while running request handler TypeError: foo at (anonymous function) (src/index.ts:10:11) 7 | 8 | async function handler(_e: FetchEvent) { 9 | const result = await buildResult(() => { > 10 | throw new TypeError('foo'); ^ 11 | }); 12 | result.headers.set('content-type', 'text/plain'); 13 | return result; at buildResult (src/index.ts:4:13) at handler (src/index.ts:9:24) at src/index.ts:1:46 Raw error below: Error while running request handler: foo Stack: handler/result<@fastly:app.js:722:11 buildResult@fastly:app.js:717:13 handler@fastly:app.js:721:24 @fastly:app.js:715:48 node_modules/@fastly/js-compute/src/rsrc/trace-mapping.inject.js/globalThis.addEventListener/<@fastly:app.js:694:33 2025-11-14T07:01:15.571068Z INFO request{id=0}: response status: 500 2025-11-14T07:01:15.571332Z INFO request{id=0}: request completed using 7.7 MB of WebAssembly heap 2025-11-14T07:01:15.571339Z INFO request{id=0}: request completed in 36ms ``` instead of ``` 2025-11-14T07:00:32.689743Z INFO request{id=0}: handling request GET http://localhost:7676/ Error while running request handler: foo Stack: handler/result<@fastly:app.js:23:11 buildResult@fastly:app.js:18:13 handler@fastly:app.js:22:24 @fastly:app.js:16:48 2025-11-14T07:00:32.692283Z INFO request{id=0}: response status: 500 2025-11-14T07:00:32.692612Z INFO request{id=0}: request completed using 7.7 MB of WebAssembly heap 2025-11-14T07:00:32.692623Z INFO request{id=0}: request completed in 3ms ``` This also catches errors at the top level. Consider the following top-level code: ```typescript async function init() { throw new TypeError('foo'); } await init(); export {}; ``` This causes an error such as the following during the Wizer step ``` Unhandled error while running top level module code TypeError: foo at init (src/index.ts:2:9) 1 | async function init() { > 2 | throw new TypeError('foo'); ^ 3 | } 4 | await init(); 5 | export {}; at __fastly_init_guard__ (src/index.ts:4:7) Raw error below: Exception while evaluating top-level script __fastly_bundle_with_sourcemaps.js:716:9 TypeError: foo Additionally, some promises were rejected, but the rejection never handled: Promise rejected but never handled: foo Stack: init@fastly:app.js:716:9 __fastly_init_guard__@fastly:app.js:718:7 @fastly:app.js:719:3 ``` instead of ``` Exception while evaluating top-level script __fastly_post_bundle.js:17:9 TypeError: foo Additionally, some promises were rejected, but the rejection never handled: Promise rejected but never handled: foo Stack: init@fastly:app.js:17:9 @fastly:app.js:20:7 ``` This is done by injecting the composed source map from esbuild and magic-string, as well as a trace mapping script into the resulting bundle. It also works with any internal or external source maps that may already exist on the input file referenced by sourceMappingURL (external or internal data-url), for example if there is an additional bundler that runs (Webpack, tsc, etc.) before js-compute-runtime. Source code contents are only included from user code (i.e., excludes node_modules and any injected code that results from transforms), and the code dump is provided for the top-most frame that exists in user code. However, this can be removed by specifying the `--exclude-sources` flag, resulting in the mapped stack trace only. This mode also makes two exported functions available from `fastly:experimental`: ```typescript /** * Get information about an error as a ready-to-print array of strings. * This includes the error name, message, and a call stack. * If --enable-stack-traces is specified during build, the call stack * will be mapped using source maps. * If --enable-stack-traces is specified and --exclude-sources is not specified, * then this will also include a code dump of neighboring lines of user code. * @param error */ export function mapError(error: Error | string): (Error | string)[]; /** * Calls mapError(error) and outputs the results to stderr output. * @param error */ export function mapAndLogError(error: Error | string): void; ``` This makes mapped error stacks available to user error handling code, e.g. ```typescript import { mapError } from 'fastly:experimental'; addEventListener('fetch', e => e.respondWith(handler(e))); async function handler(_e: FetchEvent) { let result: Response; try { throw new TypeError('foo'); result = new Response(); } catch(err) { return new Response(mapError(err).join('\n')); } return result; } ``` Then curling this would give: ``` % curl http://localhost:7676/ TypeError: foo at handler (src/index.ts:12:11) 9 | async function handler(_e: FetchEvent) { 10 | let result: Response; 11 | try { > 12 | throw new TypeError('foo'); ^ 13 | result = new Response(); 14 | } catch(err) { 15 | return new Response(mapError(err).join('\n')); at src/index.ts:3:46 ``` This feature adds a small amount of data to the Wasm package, but parsing the sourcemap does not occur on a hot code path, so runtime performance is not expected to be impacted strongly. ## Outputting intermediate files (`--debug-intermediate-files <dir>`) The bundling process has the following steps ``` input file --(bundle: esbuild)--> intermediate file 1 --(postbundle: magic-string)--> intermediate file 2 --(inject sourcemap)--> final file to pass to wizer ``` * The bundle step uses esbuild to transform modules and apply the Fastly plugin (for example fastly:* namespaces) * in the new mode, this also injects the stack trace mapping functionality * The postbundle uses magic-string to inject pre-compiled regexes * in the new mode, this also injects the initialization guard and placeholder for inserting sourcemap * The inject sourcemap step is new and replaces a marker with the final composed sourcemap content After package has been built, the runtime deletes all of the temporary files. However it is sometimes useful to have access to view the intermediate files. By specifying the `--debug-intermediate-files <dir>` flag, these intermediate files are dumped into the specified directory to aid in debugging. For example: ``` js-compute-runtime --debug-intermediate-files ./bin src/index.ts ./bin/main.wasm ``` This will output the files `__1_bundled.js` and `__2_postbundled.js` as well as `fastly_bundle.js` to the `./bin` directory, which can be examined. If `--enable-stack-traces` is also set, then intermediate source map files `__1_bundled.js.map`, `__2_postbundled.js.map`, as well as the final source map file `fastly_sourcemaps.json` will also be emitted.

Why this matters

Faster iteration and debugging at the edge and locally
Instead of deploying just to discover that “some error happened” with no useful stack info, you now see exactly which file and which line threw the error. Stack traces now point to your actual source lines, not the bundled/transpiled output.
More confidence with complex builds
Frameworks, TypeScript, and multi-module apps all benefit from accurate stack mapping.
Visibility into the build pipeline
Intermediate file dumps make it straightforward to diagnose issues that stem from bundling, transforms, loaders, or accidental code changes introduced by tooling.

Getting started

Here’s how you might set up the "build" script in your package.json:

{
  "scripts": {
    "build": "js-compute-runtime src/index.ts bin/main.wasm --enable-stack-traces"
  }
}

If you prefer not to upload your source code with the Wasm bundle, also add --exclude-sources.
Run npm run build as usual, then deploy or test locally. If an uncaught error is thrown in top level code or in the handler, you’ll now get a readable, source-mapped stack trace.

If you are catching an error in your own code, you’ll want to call mapError() (details) on it to get the mapped information.

import { mapError } from 'fastly:experimental';

try {
  // .. code that may throw
} catch(err) {
  // display error with mapped stack
  console.error(mapError(err).join('\n'));
}

Looking ahead

This release is another step in making JS development on Compute more ergonomic and transparent. If you try it out and have feedback, ideas, or issues, feel free to start a discussion here on the community forum or open an issue in the GitHub repo. We’d love to hear what you think.

Topic		Replies	Views
Test esbuild + Compute Compute	0	59	March 26, 2025
Error during 'fastly compute init' General	5	558	November 19, 2023
Squigil’s House The Gallery	10	199	September 11, 2025
Profiling Fastly Compute applications Compute compute	2	93	August 18, 2025
Error("location.href can only be used during request handling ...") Compute edge	1	877	May 2, 2023

Better debugging for JS Compute apps: Stack traces and intermediate files in JavaScript SDK 3.37

What’s new

Why this matters

Getting started

Looking ahead

Related topics