Skip to main content
Version: 6.x (latest)

External sourcemap retrieval (template URLs + secrets)

You can configure the N|Solid Console to fetch sourcemaps for CPU profiles automatically from an external endpoint, using a URL template filled in from the process's app name and tags, plus bearer-token or S3-compatible authentication. This page covers the URL template syntax, authentication options, resolution modes, and troubleshooting.

How it works​

  • You save an external storage configuration: a URL template, an authentication method, credentials, and an on/off switch.
  • When you open a CPU profile that has no sourcemap, the Console fills in the template from the profile's metadata (app name and tags) and downloads a zip file from the resulting URL.
  • Before storing the download and linking it to the profile, the Console checks that the URL is safe and that the zip contains valid .map files. Only HTTPS and S3 URLs are allowed, and localhost and private IP addresses are rejected. Downloads are limited to 100 MB, 3 same-host redirects, and a 30-second timeout.

Prerequisites​

  • If your template uses tags, start your processes with matching tags, for example NSOLID_TAGS="build:1.2.3,commit:abc123". You can also set tags in the nsolid.tags field of package.json, or in the process's Dynamic Configuration in the Console.
  • The external endpoint must serve a zip file that contains at least one valid sourcemap (*.map).
  • To change these settings, you need the settings > sourcemap storage permission. To upload sourcemaps manually with a service token, the token needs the Sourcemap Upload permission.

URL templates and metadata substitution​

The URL template supports these placeholders:

  • {app} — the asset's app name.
  • {tag:build} — the value after build: in the first matching tag. Use any tag prefix in place of build.
  • {tag:*} — the value after the colon in the first tag that contains a colon. For example, if the agent has the tag build:v1.2.3, it resolves to v1.2.3. For predictable results, use a specific prefix instead.

Examples:

  • HTTPS with a build tag: https://cdn.example.com/maps/{app}/{tag:build}.zip
  • S3 object URL: s3://my-bucket/{app}/{tag:*}/dist.zip

If the metadata is missing a value that the template needs (no app name, or a missing tag), the fetch is rejected. If a fetch fails, you can still upload the sourcemap manually.

Resolution mode​

Each process has a Sourcemap Resolution per Profile switch in its Dynamic Configuration. It controls how sourcemaps are shared between profiles:

  • ON (per profile, the default): each profile stores its own sourcemap zip. Identical content is deduplicated automatically.
  • OFF (per process): all profiles captured from the same process share one sourcemap zip, so a sourcemap fetched or uploaded once also applies to later profiles from that process.

In both modes, when external storage is enabled, the Console tries to fetch the sourcemap automatically whenever you open a CPU profile that doesn't have one.

Authentication options​

  • Bearer Token (GCP, GitHub, GitLab): sends Authorization: Bearer <token> with the request. Use it for HTTPS endpoints.
  • S3-Compatible (AWS, GCP HMAC, MinIO): signs requests with an access key ID, secret access key, and region. Works with S3-compatible services such as AWS S3, Google Cloud Storage HMAC keys, and MinIO.

Configure in the Console​

  1. Click Settings, expand Integrations in the left menu, and select Sourcemap Resolution.
  2. Enter your URL Template.
  3. Choose an Authentication Method.
  4. Enter the credentials:
    • Bearer: Bearer Token
    • S3: Access Key ID, Secret Access Key, and Region (default us-east-1)
  5. Turn the switch ON. The first time you enable the configuration, all required fields must be filled in. After that, you can rotate credentials without turning it off.
  6. Click Save (or Update, if a configuration already exists). Saved secrets are masked when you return to the page. If you don't enter new values, the existing secrets are kept.

Troubleshooting​

  • "Credentials are required for initial configuration": enter a bearer token, or both S3 keys, the first time you save the configuration.
  • "Only HTTPS URLs are allowed": use an https:// URL, or use an s3:// URL with the S3-Compatible authentication method.
  • 401, 403, and 404 responses are reported as readable errors. Check your credentials, permissions, and the template path.
  • "Required tag ... not found": add the tag to the process, or change the template.

Checklist​

  • The URL template resolves with your app name and tags.
  • The authentication method matches the endpoint (bearer for HTTPS, S3-compatible for S3 URLs).
  • Credentials are saved and rotated as needed.
  • The configuration is turned on.
  • The external endpoint returns a zip that contains valid .map files.
NodeSource Support