---
title: "Source maps"
description: "Debug IDs, the build plugin for Vite, webpack, Rollup, esbuild, Rspack and Next.js, the ezgh CLI, and uploads from GitHub Actions with no stored secret."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Source maps

Production JavaScript is minified, so a browser's stack trace points at `index-4f2a.js:1:20413`.
Source maps turn its frames back into your files, functions and lines, with the code around
them. EZGH symbolicates each error as it arrives, with the maps you uploaded for its release.

**Upload a release's maps before you deploy it.** Errors that arrive before their maps keep
their minified frames (`ezgh.rum.symbolication` is `missing`) and may be grouped into a separate
issue. Stored errors aren't symbolicated again when maps arrive later.

## Debug IDs

EZGH matches each frame to its map by **debug ID**, a UUID that a built file and its map share
(the [TC39 source map debug ID proposal](https://github.com/tc39/ecma426/blob/main/proposals/debug-id.md)):

- the JavaScript file gets a one-line snippet at the top that registers its debug ID, and a
  `//# debugId=<uuid>` comment at the end;
- the map gets a top-level `"debugId"`;
- the same build output always gets the same debug ID, and a file that already has one keeps it.

Because frames are matched by debug ID, CDNs, hashed file names and query strings don't matter.
Maps without a debug ID are refused. The build plugin and `ezgh obs sourcemaps inject` add debug
IDs the same way, byte for byte, so running both is harmless.

Upload the minified JavaScript with each map (the plugin and the CLI do): with it, frames show
your functions' original names.

## With the build plugin

`@ezghcloud/rum-build` adds debug IDs to every JavaScript file the bundler writes, then uploads the
files and their maps. Turn source maps on in the bundler: hidden maps (without a
`sourceMappingURL` comment) are fine.

```sh
npm i -D @ezghcloud/rum-build
yarn add -D @ezghcloud/rum-build
pnpm add -D @ezghcloud/rum-build
bun add -d @ezghcloud/rum-build
```

### Vite

```ts
// vite.config.ts
import { defineConfig } from "vite";
import { ezghRumBuild } from "@ezghcloud/rum-build";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [ezghRumBuild.vite({ application: "storefront", release: process.env.VITE_RELEASE })],
});
```
### webpack

```js
// webpack.config.js
const { ezghRumBuild } = require("@ezghcloud/rum-build");

module.exports = {
  devtool: "hidden-source-map",
  plugins: [ezghRumBuild.webpack({ application: "storefront", release: process.env.RELEASE })],
};
```
### Rollup

```js
// rollup.config.mjs
import { ezghRumBuild } from "@ezghcloud/rum-build";

export default {
  input: "src/main.js",
  output: { dir: "dist", format: "es", sourcemap: "hidden" },
  plugins: [ezghRumBuild.rollup({ application: "storefront", release: process.env.RELEASE })],
};
```
### esbuild

```js
// build.mjs
import * as esbuild from "esbuild";
import { ezghRumBuild } from "@ezghcloud/rum-build";

await esbuild.build({
  entryPoints: ["src/main.ts"],
  bundle: true,
  minify: true,
  outdir: "dist",
  sourcemap: "external",
  plugins: [ezghRumBuild.esbuild({ application: "storefront", release: process.env.RELEASE })],
});
```
### Rspack

```js
// rspack.config.js
const { ezghRumBuild } = require("@ezghcloud/rum-build");

module.exports = {
  devtool: "hidden-source-map",
  plugins: [ezghRumBuild.rspack({ application: "storefront", release: process.env.RELEASE })],
};
```
### Next.js

```ts
// next.config.ts
import { withEzghRum } from "@ezghcloud/rum-nextjs/config";

export default withEzghRum({ /* your config */ }, { application: "storefront" });
```

`withEzghRum` turns on client source maps, adds debug IDs to the client bundles after
`next build`, uploads them, and deletes the maps from the output so they're never served. It
takes the options below; the release comes from `EZGH_RUM_RELEASE` unless you set `release`.

The `release` must be the one your pages pass to `init`. The plugin uploads when it has
credentials, the organization and project, the application and the release; without them it only
adds debug IDs, and prints what's missing.

| Option | Default |
| --- | --- |
| `application` | `EZGH_RUM_APPLICATION` |
| `release` | `EZGH_RUM_RELEASE` |
| `organizationId`, `projectId` | `EZGH_ORG`, `EZGH_PROJECT`. These are **IDs** (UUIDs): the app's **Setup** tab shows them, and so do `ezgh orgs get` and `ezgh projects get <project>` |
| `apiKey` | `EZGH_API_KEY`: an [API key](/iam/api-keys) whose owner has `ObsSourceMapUploadAccess` or `ObsFullAccess` |
| `oidc` | `{ bot, audience? }`: in GitHub Actions, exchange the job's OIDC token for a short-lived key of `bot` when there's no API key |
| `upload` | `true`; `false` only adds debug IDs |
| `failOnError` | `true`: a failed upload fails the build. `false` prints the error instead |
| `deleteMapsAfterUpload` | `false`; `true` deletes the uploaded `.map` files from the output |

Hidden maps aren't referenced by your JavaScript, but the `.map` files stay in the output: set
`deleteMapsAfterUpload: true`, or leave them out of your deploy, if they mustn't be served.

## With the CLI

For builds without the plugin, add debug IDs after the build and upload before deploying:

```sh
ezgh obs sourcemaps inject dist
ezgh obs sourcemaps upload dist --application storefront --release 2026.10.13-4f2a9c1
```

- `inject` pairs each `.js`, `.mjs` and `.cjs` file (outside `node_modules`) with the map its
  `sourceMappingURL` comment names, or `<file>.map`, and rewrites both in place. Running it again
  changes nothing, and it keeps debug IDs a bundler already wrote (such as Rollup's
  `sourcemapDebugIds`). `--dry-run` writes nothing.
- **Deploy the injected files**: the snippet in them is what links errors to their maps.
- `upload` sends only what EZGH doesn't have yet, so after a failure, run it again to resume.
  Uploading the same files again changes nothing. `--parallel` sets how many chunks go up at a
  time (8 by default).
- `--release` must be the one your pages pass to `init`, and `--application` the client token's.

```sh
ezgh obs sourcemaps list
ezgh obs sourcemaps list --application storefront --release 2026.10.13-4f2a9c1
ezgh obs sourcemaps delete --application storefront --release 2026.10.11-91ab3e0
```

`list` shows releases, newest first, with their file count, size, when they were uploaded and
when an error last used them; with `--release`, each file's path, kind, debug ID and size.
Deleting a release stops symbolication for its errors from then on; errors already stored keep
their stack traces. [`ezgh obs sourcemaps`](/cli/reference/obs-sourcemaps) lists every flag.

## In CI, with no stored secret

In GitHub Actions, a job can upload as a [bot](/iam/bots) with its OIDC token, so no API key is
stored in GitHub. Set it up once, signed in:

```sh
ezgh iam bots create sourcemaps
ezgh iam policies attach ObsSourceMapUploadAccess --bot sourcemaps
ezgh iam oidc-providers create github --issuer https://token.actions.githubusercontent.com
ezgh iam bots oidc-trust add sourcemaps --provider github \
  --subject 'repo:*:ref:refs/heads/main' --claim repository_id=<your repository ID>
```

`ObsSourceMapUploadAccess` can upload and list source maps and nothing else. Get the repository's
ID with `gh api repos/<owner>/<repo> --jq .id`; [Use GitHub Actions without stored keys](/iam/github-actions)
explains the trust entries.

Then in the workflow, give `setup-ezgh` your organization's **ID**, since the build plugin reads
it from `EZGH_ORG`:

```yaml
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ezgamehost/setup-ezgh@v1
        with:
          org: 0199a3b4-0000-7e5f-8a9b-1c2d3e4f5a6b # the organization's ID
          bot: bot_8k2l4m6n8p0q
      - run: npm ci && npm run build
        env:
          VITE_RELEASE: ${{ github.sha }}
          EZGH_PROJECT: 0199a3b4-1111-7e5f-8a9b-1c2d3e4f5a6b # the project's ID
```

The plugin uploads during the build, with the key `setup-ezgh` put in `EZGH_API_KEY`. Without the
plugin, build, then run
`ezgh obs sourcemaps inject dist && ezgh obs sourcemaps upload dist --application storefront --release "$GITHUB_SHA"`.
For clusters, see [Kubernetes service accounts](/iam/kubernetes). A stored API key of the same
bot works too, in `EZGH_API_KEY`.

## Retention and limits

A release's maps are deleted 90 days after an error last used them, and an application keeps its
newest 50 releases. A project holds up to 10 GiB of source maps. See
[Limits](/observability/rum/limits#source-maps).

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| Errors show minified frames (`ezgh.rum.symbolication` is `missing`) | The release's maps weren't uploaded, or the deployed files aren't the injected ones. Compare the `//# debugId=` at the end of the deployed file with `ezgh obs sourcemaps list --application <app> --release <release>` |
| Some frames are mapped and others aren't (`partial`) | Maps are missing for some of the files in the stack, such as a chunk built separately |
| `409 debug_id_conflict` | A file with the same debug ID and different content is already uploaded: a file changed after its debug ID was added. Build again and upload the new output. `error.details.debugIds` lists them |
| `409 storage_limit_exceeded` | The project's source maps are at 10 GiB. Delete releases you no longer need |
| `409 chunks_missing` | A commit named chunks EZGH doesn't hold. The CLI and the plugin upload them and retry; see the API below |

## API

For tool authors. Under `/v1/organizations/<organization ID>/projects/<project ID>/obs/` at
`https://obs.ezghcloud.com`, an upload has three steps:

1. Split each file into 8 MiB chunks: every chunk but the last is exactly 8,388,608 bytes. Ask
   which chunks EZGH doesn't have, 1,000 hashes at a time:
   [`POST source-maps/chunks/missing`](/obs-api/CheckSourceMapChunks/) with
   `{ "hashes": ["<sha256 hex>", …] }` answers `{ "missing": […] }`.
2. Upload each missing chunk:
   [`POST source-maps/chunks`](/obs-api/UploadSourceMapChunk/) with the chunk as the
   `application/octet-stream` body and its hash in `x-ezgh-sha256`.
3. Commit the files to a release:
   [`POST source-maps`](/obs-api/UploadSourceMaps/) with up to 1,000 files.

```json
{
  "application": "storefront",
  "release": "2026.10.13-4f2a9c1",
  "files": [
    { "debugId": "1ebe9078-1fbe-720b-80be-93c3a1f0d2e4", "path": "assets/index-c81d2e7.js.map", "kind": "map", "size": 689152, "chunks": ["e3b0c442…"] },
    { "debugId": "1ebe9078-1fbe-720b-80be-93c3a1f0d2e4", "path": "assets/index-c81d2e7.js", "kind": "js", "size": 202752, "chunks": ["9f86d081…"] }
  ]
}
```

- A commit adds to the release; commit a debug ID's `js` and `map` together. Each map must be a
  source map (version 3) whose `debugId` is the file's.
- A chunk EZGH doesn't hold is `409 chunks_missing`, with the hashes to upload in
  `error.details.missing`: upload them and commit again.
- [`GET source-maps`](/obs-api/ListSourceMaps/) lists releases (`application`, `release`,
  `files` (how many), `bytes`, `createdAt`, `lastUsedAt`), filtered by `application`; with
  `application` and `release`, `files` is the release's files, each with its `debugId`, `path`,
  `kind` and `size`.
  [`DELETE source-maps?application=…&release=…`](/obs-api/DeleteSourceMaps/) deletes a
  release.
- Nothing returns a map's content.

Source: https://docs.ezghcloud.com/observability/rum/source-maps/index.mdx
