Source maps guide
Source maps: see your own code in stack traces
In production, an error points to page-3f2a.js, line 1, column 18204. With your source maps, Errilo shows the original file, line and function, with the code around the error. Uploads happen at build time, with the Sentry tools you already use.
Errilo is in development. This guide describes the setup our compatibility suite tests today; the private beta opens in summer 2027.
How it works
At build time, each JavaScript file gets a debug ID: a unique identifier written into the file and into its source map. The Sentry build plugin then uploads the files and their source maps to Errilo. When an error comes in, its frames carry these debug IDs, so Errilo finds the right source map without relying on a release name.
Frames are translated as the error is received, before it is stored: original file, line, column and function, plus five lines of code before and after. Issues are grouped on the original code, so the same error from two different builds lands in the same issue.
A debug ID is only looked up in the project that received the source maps, never across projects.
1. Create a token
In Errilo, open Settings, section API tokens, then New token, and tick the project:releases scope (“Manage releases”). Restrict it to the project you’re uploading for: that’s all a CI needs.
The token (errilo_…) is shown only once: store it right away in your CI secrets. Without the project:releases scope, uploads are refused with a 403.
2. Set the build variables
The Sentry build plugin reads four variables from the build environment:
| Variable | Value |
|---|---|
SENTRY_URL | The address of the Errilo app, https://app.errilo.com/, not the event ingestion address |
SENTRY_ORG | Your organization’s slug |
SENTRY_PROJECT | The slug of the project that receives the errors, the one whose DSN your app uses |
SENTRY_AUTH_TOKEN | The token from step 1 |
SENTRY_URL=https://app.errilo.com/
SENTRY_ORG=<your-errilo-organization>
SENTRY_PROJECT=<your-errilo-project>
SENTRY_AUTH_TOKEN=errilo_...Never commit SENTRY_AUTH_TOKEN and never expose it to the browser: no NEXT_PUBLIC_ prefix.
3. Next.js: nothing to configure
@sentry/nextjs does everything during next build: it writes the debug IDs, uploads the source maps of the server and the browser, and creates the release. Your next.config.js keeps its usual Sentry setup, with no organization, project, token or URL in it (see the Next.js guide for the rest of the setup):
// SDK 9: require("@sentry/nextjs")
const { withSentryConfig } = require("@sentry/nextjs/config");
module.exports = withSentryConfig({
// your Next.js config
});Then run the build with the four variables in its environment:
# SENTRY_AUTH_TOKEN comes from your CI secrets
export SENTRY_URL=https://app.errilo.com/
export SENTRY_ORG=my-organization
export SENTRY_PROJECT=my-project
pnpm buildOur compatibility suite builds a production Next.js 15 app with each version below, uploads its source maps with the plugin and these variables only, then checks that a server error and a browser error arrive with their original file, line and code.
| Major version | Tested version |
|---|---|
| v9 | @sentry/[email protected] |
| v10 | @sentry/[email protected] |
| v11 | @sentry/[email protected] |
4. Other build tools: sentry-cli
Coming soon: our compatibility suite doesn’t check uploads with sentry-cli yet (Vite, Nuxt, SvelteKit, webpack, esbuild…).
For any other JavaScript app, generate source maps at build time, then run sentry-cli on the build folder, with the same four variables:
sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload ./distinjectwrites a debug ID into each JavaScript file and its source map. Run it before you deploy: the injected files are the ones to serve.uploadsends the files and their source maps.- Don’t change a file after injecting it, for example with a second minification pass: its debug ID would no longer match its source map.
When a frame stays minified
The error is always stored, with its minified frames. The issue page shows “Symbolication failed for N files”, with each file’s path, its debug ID and one of these causes:
| Message | What to check |
|---|---|
| “No source map was uploaded for this file.” | Did the upload succeed (plugin output, valid token)? Is SENTRY_PROJECT the project whose DSN receives the errors? Is the file you serve the one that was uploaded? Did the error arrive after the upload was processed? |
| “The source map for this file is unreadable or too large.” | A source map is limited to 32 MiB. Check that the upload contains the .map file and that it is valid JSON. |
| “The frame position does not exist in the source map.” | The file was changed after its source map was generated (a banner added, a second minifier). Generate the map last, then inject, then upload. |
Frames translated but with no code around them: the source map has no sourcesContent. Turn it on in your build tool; most enable it by default.
The upload itself fails:
- 401 or 403: the token is missing, revoked or expired, or lacks the
project:releasesscope. - 404 on the organization:
SENTRY_ORGisn’t the slug of an organization the token gives access to.
Known limits
- Only errors received after the upload are translated: an error already stored isn’t processed again.
- An issue created before the source maps were uploaded isn’t merged with the new one, because it was grouped on the minified code. Resolve the old one by hand.
@sentry/nextjs11.12.0: the frame of a server route’s own entry file points tosentry-wrapper-moduleinstead of your file. The SDK adds a banner to that file without updating its source map; the other frames are translated.