cloudflare / cloudflare/workerd

🚀 Feature Request: Source map support for Worker Loader (dynamic workers) stack traces

Open
#6,870 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
8.7k
Forks
739
Avg merge
2d 20h
Merged PRs (30d)
174

Description

## Summary

There is currently no way to get source-mapped stack traces for Workers loaded via the Worker Loader binding (dynamic workers). Errors thrown inside a dynamically loaded, bundled Worker surface with positions in the bundled module, and none of the existing source-map machinery applies:

- `Error.stack` inside the isolate is never remapped at runtime (expected — this matches deployed Workers).
- The deployed-Worker remapping pipeline (`upload_source_maps = true`) doesn't apply, because loader-provided code never goes through the upload path.
- `WorkerLoaderModule` has no field to attach a source map: `{ js, cjs, text, data, json, py, wasm }`.
- Exceptions delivered to `tails` / `streamingTails` attached via `WorkerLoaderWorkerCode` also arrive with raw (bundled) positions.

## Use case

We run user-submitted code in dynamic workers, bundled with [`@cloudflare/worker-bundler`](https://www.npmjs.com/package/@cloudflare/worker-bundler) (`bundle: true` is needed for npm dependency support). The bundler's `sourcemap: true` option inlines an esbuild source map into the emitted module, but nothing consumes it: when the user's code throws, the stack we report back to them points at bundle line numbers instead of their own source, which makes errors materially harder for end users to act on.

This seems like it will be a common need for the Worker Loader's headline use case (running dynamically generated / user-provided code, often bundled from TypeScript or multiple files).

## Proposal

Some options, roughly in order of preference:

1. Accept a source map alongside a module, e.g. a `sourceMap` field on `WorkerLoaderModule` (or honor inline `//# sourceMappingURL=data:...` comments), and use it to remap stack traces in exceptions delivered to the loader's `tails` / `streamingTails` and to Workers Logs — mirroring the out-of-band remapping that deployed Workers get with `upload_source_maps`.
2. Expose the remapping as an API the host Worker can call (give the loader/stub a way to remap a stack string for a worker it loaded).

## Workaround today

Host-side remapping: emit an inline source map (`sourcemap: true` in worker-bundler), have the dynamic worker return `e.stack` to the host, and remap frames in the host Worker with `@jridgewell/trace-mapping` against the map extracted from the bundled module. This works but every Worker Loader consumer has to rebuild it.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the WorkerLoaderModule and WorkerLoaderWorkerCode entry points, including how tails and streamingTails deliver exceptions. Compare those paths with the deployed-Worker upload_source_maps remapping pipeline; done means a selected source-map input or API remaps dynamic-worker stack positions in the specified exception and logs surfaces.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
backend-api-design, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.