Error Debugging

When there are any production errors, it is difficult to debug as the stack trace is minified. To solve this problem, upload source map files to the Middleware, which allows you to see the source code and stack trace of the errors that occur in your minified or transpiled code.

Uploading Source Maps

CLI

1 Install the Middleware sourcemap uploader

Install the uploader once so the sourcemap-uploader command is available in your CI or shell.

1npm install -g @middleware.io/sourcemap-uploader

2 Enable Source Maps in Your Build

Your bundler must emit source maps.

Webpack
Next.js
1module.exports = {
2  devtool: "source-map",
3};
1module.exports = {
2  productionBrowserSourceMaps: true,
3};

Keep the generated .map files in your build output directory—your uploader will read from this path in the next step.

3 Upload after Building

Run the CLI after your build finishes. Point it at your sourcemap directory and specify the app version that matches your RUM init.

Account key note: Use your RUM account key (this is different from the general Middleware API key). You can find it on the Installation page in your dashboard.

1sourcemap-uploader upload \
2  --apiKey=<rum_account_key> \
3  --path="/path/to/sourcemaps" \
4  --appVersion="1.0.0"

sourcemap-uploader arguments

  • --apiKey — Your RUM account key.
  • --path — Directory to scan for .map files (defaults to current directory).
  • --appVersion — Version of this deployment. This must match the app.version you set in defaultAttributes when you call Middleware.track.
    • If omitted, sourcemaps are uploaded as latest.
    • If it doesn’t match your app.version, original stack traces won’t be generated.

Removing Sourcemaps from the Build Directory (optional)

After you upload sourcemaps, you may want to remove them and strip references from production artifacts:

1# Delete source maps
2find /path -type f -name '*.js.map' -delete
3find /path -type f -name '*.css.map' -delete
4# Delete source map references
5find /path -type f -name '*.js'  -exec sed -i -E 's/sourceMappingURL=[^ ]*\.js\.map//g'  {} +
6find /path -type f -name '*.css' -exec sed -i -E 's/sourceMappingURL=[^ ]*\.css\.map//g' {} +
Webpack
Next.js

You can upload sourcemaps using the Webpack plugin available in @middleware.io/sourcemap-uploader/dist/webpack-plugin.

To use the plugin, edit webpack.config.js to add a new entry in the plugins array at the top level of the file, and ensure Webpack is producing sourcemaps:

1const MiddlewareWebpackPlugin = require("@middleware.io/sourcemap-uploader/dist/webpack-plugin").default
2module.exports = {
3  // Ensure that Webpack has been configured to output sourcemaps.
4  devtool: 'source-map',
5  // ...
6  plugins: [
7    // Enable our plugin to upload the sourcemaps once the build has completed.
8    // This assumes NODE_ENV is how you distinguish production builds. If that
9    // is not the case for you, you will have to tweak this logic.
10  ]
11}

Webpack Plugin Options

The plugin provides options to locate source maps and build artifacts on disk and configure upload paths to match your project layout.

FieldTypeDescription
apiKeystringA unique key used to authenticate/authorize the upload of source maps.
appVersionstringThe version of your app (e.g., 1.2.0, v3.1-beta) is tied to the uploaded maps. Must match defaultAttributes["app.version"] in your RUM init.
pathstringAbsolute/relative file path from which source map files are uploaded (where your .map files live).
basePathstringRoot path in your codebase/build output where the original sources live. Helps resolve original file locations during error unminification.

The plugin uploads sourcemaps to the workspace associated with your apiKey and automatically associates them with build artifacts in error tracking when you debug issues.

Next.js uses Webpack internally, so you’ll configure the same plugin in next.config.js, and enable production sourcemaps:

1const MiddlewareWebpackPlugin =
2  require("@middleware.io/sourcemap-uploader/dist/webpack-plugin").default;
3
4const nextConfig = {
5  productionBrowserSourceMaps: true,
6
7  webpack: (config) => {
8    config.plugins.push(
9      new MiddlewareWebpackPlugin(
10        "<ACCOUNT_KEY>", // Account key of the application.
11      )
12    );
13    return config;
14  }
15}

Also see Next.js docs on Configuring the Build ID for generating a consistent build ID (for example, from a Git hash).

Verify and Troubleshoot

  • Stacks are Still Minified
    • Confirm the --appVersion used at upload equals defaultAttributes["app.version"] in your Middleware.track call.
    • Ensure the uploader ran after your build step and before any cleanup (if you remove .map files).
  • No .map files found
    • Double-check your bundler is emitting source maps: devtool: "source-map" (Webpack) or productionBrowserSourceMaps: true (Next.js).
    • Confirm the directory passed to --path actually contains the .map files that correspond to the minified assets served to users.
  • Plugin Config Uncertainties
    • Start with apiKey and appVersion. Add path and basePath only if your project layout needs them (e.g., monorepos or custom output folders).

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.