JS Error Hub

Local Symbolication with Mozilla source-map Library

Implement offline stack trace resolution using Mozilla’s source-map library to decode minified production errors without relying on external SaaS platforms. This workflow enables deterministic local debugging, CI/CD pipeline integration, and secure artifact handling.

Key implementation capabilities include:

  • Asynchronous WASM-backed consumer initialization for optimal parsing performance
  • Direct file system mapping for secure, air-gapped symbolication environments
  • Strict adherence to v3 spec coordinate normalization (1-based lines, 0-based columns)
  • Memory lifecycle management to prevent heap exhaustion during batch processing

Environment Setup & WASM Initialization

Configure the Node.js runtime to load the library and initialize the underlying WebAssembly module before consuming map files. Install the package via npm install source-map and verify Node.js v18+ compatibility. The library relies on a compiled WASM binary for high-performance VLQ decoding.

You must preload this asset using SourceMapConsumer.initialize() before instantiating any consumers. Failing to await this promise causes race conditions during runtime execution. Validate your build pipeline alignment with foundational Source Map Generation & Stack Trace Debugging workflows to ensure artifact parity before local resolution.

const sourceMap = require('source-map');
const fs = require('fs/promises');
const path = require('path');

async function initConsumer(mapPath) {
 await sourceMap.SourceMapConsumer.initialize({
 'lib/mappings.wasm': path.join(__dirname, 'node_modules/source-map/lib/mappings.wasm')
 });
 const rawMap = await fs.readFile(mapPath, 'utf-8');
 return new sourceMap.SourceMapConsumer(rawMap);
}

This pattern demonstrates mandatory async WASM initialization and synchronous consumer creation from a local file system path. Always resolve the initialization promise before proceeding to artifact ingestion.

Loading & Parsing Source Map Artifacts

Ingest raw .map JSON payloads from local storage and instantiate a SourceMapConsumer for coordinate resolution. Use fs.promises.readFile to stream large map files into memory without blocking the event loop. Pass the raw JSON string directly to the constructor for synchronous instantiation.

Implement fallback logic when sourcesContent is stripped during production builds. The library does not auto-fetch external files over HTTP or the file system. Cross-reference your output paths with Configuring Webpack for Production Source Maps to resolve relative source paths correctly when parsing stripped artifacts.

async function loadMapArtifact(mapPath) {
 const rawMap = await fs.readFile(mapPath, 'utf-8');
 const consumer = new sourceMap.SourceMapConsumer(rawMap);
 
 if (!consumer.sourcesContent) {
 console.warn('sourcesContent stripped. Manual file resolution required.');
 }
 
 return consumer;
}

Stream large payloads directly into memory. Check for missing source content early to trigger custom file resolution logic before coordinate mapping begins.

Resolving Minified Stack Frames

Map minified error coordinates to original source locations using the originalPositionFor API. Extract line and column values from minified stack traces using regex or error parsing middleware. Invoke the API with strict 1-based line indexing and 0-based column indexing.

Handle null or { source: null } returns, which indicate unmapped generated code or polyfill boundaries. Align your column offsets with Vite Build Settings for Accurate Stack Traces to prevent off-by-one resolution errors during frame translation.

async function resolveFrame(consumer, minifiedLine, minifiedColumn) {
 const original = consumer.originalPositionFor({
 line: minifiedLine,
 column: minifiedColumn
 });
 if (!original.source) return { resolved: false, reason: 'No mapping found' };
 return {
 resolved: true,
 file: original.source,
 line: original.line,
 column: original.column,
 name: original.name || '<anonymous>'
 };
}

This snippet shows coordinate normalization, null-check handling, and structured return payload generation for downstream log parsers. Always verify column indexing matches the V8 error format.

Automating Batch Symbolication Pipelines

Orchestrate high-throughput error decoding for QA and SRE log aggregation workflows. Implement LRU caching for frequently accessed SourceMapConsumer instances to reduce disk I/O. Process error arrays in parallel using Promise.allSettled to isolate failed frame resolutions without crashing the worker thread.

Always call consumer.destroy() after batch completion to free WASM memory allocations. Output structured JSON reports containing original file paths, line numbers, and function names for downstream indexing and alerting systems.

async function batchSymbolicate(consumer, errorFrames) {
 const results = await Promise.allSettled(
 errorFrames.map(f => resolveFrame(consumer, f.line, f.column))
 );
 consumer.destroy(); // Free WASM memory
 return results.map(r => r.status === 'fulfilled' ? r.value : { error: r.reason });
}

This pattern illustrates parallel execution, graceful failure isolation, and mandatory destroy() invocation. Omitting the cleanup step causes memory leaks in long-running processes.

Common Mistakes

  • Synchronous WASM initialization blocking the event loop: Calling initialize() without await causes subsequent new SourceMapConsumer() calls to throw WASM not loaded errors. Always await initialization before instantiation.
  • Off-by-one column indexing errors: Stack traces use 1-based line indexing but 0-based column indexing. Passing 1-based columns to originalPositionFor shifts resolution to adjacent tokens or returns null.
  • Memory exhaustion from unclosed consumers: Each SourceMapConsumer holds a persistent WASM memory buffer. Failing to call consumer.destroy() after processing causes heap growth and eventual OOM crashes in CI/CD or log aggregation workers.

FAQ

Can the Mozilla source-map library run in browser environments? Yes, but it requires bundler configuration to serve the WASM file via HTTP. Node.js or Bun is recommended for local symbolication due to direct file system access and lower latency.

How do I handle source maps with externalized sources instead of sourcesContent? Parse the sources array, resolve relative paths against the map file location, and read original files from disk. The library does not auto-fetch external sources.

What is the performance impact of symbolicating thousands of frames? Resolution operates at O(log n) per frame. Batch processing with cached consumers typically handles 10k+ frames per second. Always destroy consumers post-batch to reclaim WASM memory.