Source Maps

Learn how to enable readable stack traces in your Sentry errors.

To enable readable stack traces in your Sentry errors, you need to upload your source maps to Sentry.

Readable Stack Traces

If you installed the Remix SDK with the Sentry Wizard, source maps upload was already configured for you. Whenever you run the build script in your package.json source maps will be uploaded automatically.

If you installed the SDK manually or the wizard failed, follow the steps below to manually configure source maps upload.

Starting from version 2.2.0, Remix supports Vite as a build tool, and from Remix version 2.7.0 it's stable and the recommended way to build your application.

If you use Vite to build your project, you can use the Vite plugin to upload source maps to Sentry.

First, install the plugin if you haven't already done so:

npm install @sentry/vite-plugin --save-dev

Then, add the plugin to your Vite configuration:

import { defineConfig } from "vite";
import { vitePlugin as remix } from "@remix-run/dev";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  plugins: [
      // ... your Remix plugin options
      // If you use .sentryclirc or environment variables,
      // you don't need to specify these options
      authToken: "",
      org: "",
      project: "",
  build: {
    sourcemap: true,
    // ... rest of your Vite build options

  // ... rest of your Vite config

To see the full list of options, refer to the Vite plugin documentation.

If you're not using Vite to build your project, you can use the sentry-upload-sourcemaps script to upload source maps to Sentry.

The Sentry Remix SDK provides a script to automatically create a release and upload source maps after you've built your project. Under the hood, it uses the Sentry CLI.

This script requires setting an auth token, which can either be done through a .sentryclirc file in the root of your project or through environment variables:

# Do not commit this file to your repository!
# Sentry Auth tokens should be treated as a secret.

Next, adjust your package.json's production build command to include the sentry-upload-sourcemaps script:

  "scripts": {
    "build": "remix build --sourcemap && sentry-upload-sourcemaps --org example-org --project example-project"

Alternatively, you can run the script directly with npx:

npx sentry-upload-sourcemaps --org example-org --project example-project

# For usage details run
npx sentry-upload-sourcemaps --help

Remix validly discourages hosting source maps in production. After uploading the maps to Sentry, we suggest you delete the .map files. The sentry-upload-sourcemaps script will automatically try to delete all generated source maps after they're uploaded (unless the --deleteAfterUpload flag is provided).

If you want to be extra sure they're deleted, you can use the following shell script:

find ./public/build -type f -name '*.map' -delete
find ./build -type f -name '*.map' -delete

Please note that these commands might vary for the operating system or shell you use.

By default, if Sentry can't find the uploaded files it needs, it will attempt to download them from the URLs in the stack trace. To disable this, turn off "Enable JavaScript source fetching" in either your organization's "Security & Privacy" settings or your project's general settings.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").