vitejs/vite · error · TypeError

Cannot use "sourcemapInterceptor: 'node'" because global "pr

Error message

Cannot use "sourcemapInterceptor: 'node'" because global "process" variable is not available.

What it means

Thrown by enableSourceMapSupport when the runner is configured with sourcemapInterceptor: 'node' but the global process variable is undefined. The 'node' interceptor mode uses Node.js's built-in process.setSourceMapsEnabled() to remap stack traces, which requires the process global. In environments where process is not available (browsers, some edge runtimes, sandboxed contexts), this configuration is invalid.

Source

Thrown at packages/vite/src/module-runner/sourcemap/index.ts:7

import type { ModuleRunner } from '../runner'
import { interceptStackTrace } from './interceptor'

export function enableSourceMapSupport(runner: ModuleRunner): () => void {
  if (runner.options.sourcemapInterceptor === 'node') {
    if (typeof process === 'undefined') {
      throw new TypeError(
        `Cannot use "sourcemapInterceptor: 'node'" because global "process" variable is not available.`,
      )
    }
    /* eslint-disable n/no-unsupported-features/node-builtins -- process.setSourceMapsEnabled and process.sourceMapsEnabled */
    if (typeof process.setSourceMapsEnabled !== 'function') {
      throw new TypeError(
        `Cannot use "sourcemapInterceptor: 'node'" because "process.setSourceMapsEnabled" function is not available. Please use Node >= 16.6.0.`,
      )
    }
    const isEnabledAlready = process.sourceMapsEnabled ?? false
    process.setSourceMapsEnabled(true)
    return () => !isEnabledAlready && process.setSourceMapsEnabled(false)
    /* eslint-enable n/no-unsupported-features/node-builtins */
  }
  return interceptStackTrace(
    runner,
    typeof runner.options.sourcemapInterceptor === 'object'
      ? runner.options.sourcemapInterceptor

View on GitHub (pinned to 89620f09af)

Solutions

If running in a non-Node environment, omit sourcemapInterceptor or set it to an object with custom retrieveFile/retrieveSourceMap handlers.
If you need source map support in-browser, use the default interceptor (omit the option) which uses Error.prepareStackTrace-based interception.
If running in Node, ensure the process global is available (don't override or delete it).
Set sourcemapInterceptor: false to disable source map interception entirely if you don't need it.

Example fix

// before — requires Node process global
const runner = new ModuleRunner({
  transport,
  sourcemapInterceptor: 'node'
})
// after — use default interceptor (works in any environment)
const runner = new ModuleRunner({
  transport
  // sourcemapInterceptor omitted -> uses prepareStackTrace-based interception
})

Defensive patterns

Strategy: validation

Validate before calling

// Validate environment supports node sourcemap interceptor before using it
function resolveSourcemapInterceptor(option) {
  if (option === 'node') {
    if (typeof process === 'undefined') {
      throw new Error('sourcemapInterceptor: "node" requires global process. Use default or false.')
    }
    if (typeof process.setSourceMapsEnabled !== 'function') {
      throw new Error('sourcemapInterceptor: "node" requires Node >= 16.6.0')
    }
  }
  return option
}

const runner = new ModuleRunner({
  transport,
  sourcemapInterceptor: resolveSourcemapInterceptor('node')
})

Type guard

function supportsNodeSourcemapInterceptor(): boolean {
  return typeof process !== 'undefined' &&
         typeof process.setSourceMapsEnabled === 'function'
}

Try / catch

try {
  const runner = new ModuleRunner({
    transport,
    sourcemapInterceptor: 'node'
  })
} catch (e) {
  if (e.message.includes('sourcemapInterceptor')) {
    console.warn('Node sourcemap interceptor unavailable, falling back to default')
    runner = new ModuleRunner({ transport }) // default interceptor
  }
}

Prevention

Only use sourcemapInterceptor: 'node' when running in a confirmed Node.js environment (>= 16.6.0).
Omit the option or use the default interceptor for browser/edge/Deno runtimes.
Add an environment check helper that all runner instances use to validate interceptor config.
Set sourcemapInterceptor: false when source maps aren't needed to avoid overhead.

When it happens

Trigger: Creating a ModuleRunner with { sourcemapInterceptor: 'node' } in a non-Node environment, or in a Node context where process has been polyfilled away or is not exposed globally (e.g., some bundlers strip process, or a custom runtime overrides globals).

Common situations: Running the module runner in an edge worker, browser extension context, or Deno (without --unstable-node-globals) where process is not defined. Using a bundler that replaces process.env but not the process global itself. Sandbox environments (vm2, isolated-vm) that don't expose process.

Related errors

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/8308df14603d1528.json. Report an issue: GitHub.