Raygun will automatically give you complete stack traces and error occurrence data from your minified JavaScript. We support both public and private source maps.

Minified files save space and make loading of pages faster, but sometimes make it hard for Raygun to pull out the error details and show a readable stack trace. To counteract this we need customers to upload their source maps to Raygun or make them available for us to fetch from their application, so we can do some magic to pull out the right information and show a readable stacktrace.

Some security conscious companies will not want to upload source maps to us or make them publicly accessible. For this we can support private source maps which solves this issue for them. Refer to the specific language provider documentation for more information on source maps as they are only used with certain languages and frameworks.

When dealing with minified JavaScript the information supplied in stack traces does not provide accurate line/column information to track down the source of the error. To deal with this you can utilize a source map which will provide the translation between the original JavaScript source and the minified version.

Raygun requires the following to complete the decoding process:

  • Payloads sent from a valid JS provider. This includes Raygun4JS and Raygun4Node (if enabled within the JS source map center).
  • Valid line/column numbers to be present in at least one line of the stack trace
  • An accessible minified JavaScript file as specified in the stack trace. This is either downloaded or retrieved from the source map center to determine if there is map file present
  • The map file to be correctly indicated in the minified JavaScript file using a footer comment (i.e. //# Note: See the instructions below for how to work around this if the footer comment is not generated during your build.
  • An accessible source map file (either publicly hosted or uploaded to the source map center)
  • To provide inline code snippets we also require the sources content field of the map file to be present or for the map file to point to publicly accessible unminified source JavaScript files. If neither of these are provided decoding of line numbers and variable names can still succeed but no inline code will be displayed with the stack trace

note: Sourcemaps do not support custom providers names. To use sourcemaps with a custom provider, you will need to specify an appropriate client name matching raygun4js (raygun-js) or raygun4node (raygun-node). See the API reference here.

We recommend using UglifyJS2 to generate a source map file.

Both the minified JS and its map file should use relative pathing. Look into the -p and --source-map-root options.

If you do not wish to have publicly accessible JavaScript files you can upload them directly to Raygun from the JS Source Map Center. This is within the Application Settings submenu on the main dashboard.

Within the Source Map Center you can upload files and label them with the URL they would normally be accessed from. When a JavaScript error is mapped we will use the files you uploaded instead of trying to access them from your servers.

In addition to the upload page we offer an API endpoint, the URL is displayed in the Source Map Center and is specific to each application.

Simply send a post request with "URL" and "file" parameters specified to upload the file. Any existing files with the same URL will be overwritten.

The request must be authenticated by adding either a basic auth header for a user with access to the application (eg. "Authorization: Basic MyBasicAuthToken") or an External Access Token appended as a querystring parameter (eg. "").

External Access Tokens can be generated from your user settings page.

Here is a cURL example request using Basic Authorization:

  -F "url="
  -F "file=@C:\website\js\myjs.min.js"

Here is an example using the Grunt plugin grunt_http_upload using an External Access Token:

http_upload: {
  your_target: {
    options: {
      url: '',
      method: 'POST',
      data: {
        url: ''
    src: 'C:\website\js\myjs.min.js',
    dest: 'file'

To get started you will need a tool which can help produce a source map as part of producing a minified version of your JavaScript. We personally use UglifyJS and find it to be a great tool. To install it you will need Node.js installed, you can then run:

npm install uglify-js -g

This will install Uglify so that it's globally available which is what you will typically want.

To produce minified JavaScript we can simply run

uglifyjs example.js -o example.min.js

To produce minified JavaScript with a mapping file we can run

uglifyjs example.js -o example.min.js --source-map

This produces the minified file "example.min.js" as well as a source map file ""

If you deploy the minified file example.min.js to production but do not wish for any or some of these files to be publicly accessible you will need to upload these files to Raygun to get source mapped stacktraces.

You can do this from within Raygun by accessing the JS Source Map Center in the Application Settings sub menu.

Screenshot of the JS Source Center in the Raygun application sidebar menu.

Here you can simply select the minified, mapping and source files to upload. After uploading you can type the URL the resource is mapped to so when our source mapping process tries to retrieve the file, it uses the file you uploaded instead.

You can determine the URL to enter by looking at the map file's "file" and "sources" properties. You can then prepend the URL of the minified file on production minus the filename.

For instance, if we have a minified file example.min.js located at and we upload example.min.js, example.js and to Raygun. We would assign their URLs like this:

Screenshot of the sourcemap center user interface.

After the files are uploaded they will be used in the source mapping processes. This is what your mapped stacktrace will look like:

Screenshot of the output of a mapped stacktrace which has been derived from the source map provided.

With many mobile applications being written in JavaScript within containers such as Apache Cordova, using Raygun4js is an appealing way to track errors across all platforms. However, as the application is hosted on the phone instead of a website with a static URL you may find that error stacktraces contain files paths which differ across different platforms and devices. This introduces some difficulty when trying to utilize source maps which require the minified and mapping files to be uploaded and labeled with exactly the same URLs as would appear in a stacktrace.

For this reason we recommend adding a handler to the raygun4js provider to rewrite file's URLs before the error is reported back to Raygun. This means that errors will be reported from the same domains and not unique domains for every platform or device.

An example of such a handler is shown below:

//handler method
var beforeSend = function(payload) {
  var stacktrace = payload.Details.Error.StackTrace;

  var normalizeFilename = function(filename) {
      var indexOfJsRoot = filename.indexOf("js");
      return '' + filename.substring(indexOfJsRoot);

  for(var i = 0 ; i < stacktrace.length; i++) {
      var stackline = stacktrace[i];
      stackline.FileName = normalizeFilename(stackline.FileName);
  return payload;

//attaching the handler to the Raygun provider

This handler removes the platform and device specific paths from the URLs present in an error's stacktrace.

For instance an error occuring on an Android phone within the file


and on an iOS device within the file


will both report

as the URL of the file within which the error occurred.

This allows the use of a single set of sourcemaps for source mapping across all deployments.


There could be up to a 30 minute delay before the mapping process starts utilizing any uploaded files. To reprocess any errors which occur during this time simply hit the "Re-process this error for Source Maps" button on an error instance.

Code snippet insertion is only available if there are less than 50 source files referenced in the map file.

Raygun supports source mapping for Node.js stacktraces which include column numbers. To enable this feature simply upload your map files as per the instructions on this page and enable the processing of Node.js errors with this setting in Raygun.

Node.js option for source maps

Files in the JavaScript Source Map Center can be managed via a few API calls.

A GET request to[applicationIdentifier] will return a JSON object listing all files within the center. eg.

  -X GET


  "Count": totalNumberOfItems,
  "Items": [
       "Url": "https://urlOfItem",
       "FileName": "fileName.js",
       "UploadedOn": "2016-01-01..."

A DELETE request to[applicationIdentifier]/all will remove all files within the center. eg.


A DELETE request to[applicationIdentifier] will remove files with the specified URLS from the center. eg.

  -F "url="[applicationIdentifier]

All requests use the same authentication methods as the upload call (Basic Authentication and Token Authentication).

If your generated minified file does not include the //# sourceMappingURL=... pragma at the end of the script, you can upload the .map file to the Source Map Center and set the URL to be the original minified source file URL.

  • Source file:
  • Map file:
  1. Upload the map file
  2. Set the URL field to be the source file URL

Screenshot showing the source map center with the map file uploaded and the URL field set to the source file URL.