---
title: "Edge Sandbox Context"
description: "The Edge Sandbox Context subsystem provides a controlled virtual machine execution environment for running Edge Runtime functions, middleware, and API routes within Next.js. Because Edge functions ..."
last_updated: "2026-09-23T10:52:03.128635+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/edge-and-sandbox/edge-sandbox-context"
---
Relevant source files
The following files were used as context for generating this wiki page:
- [packages/next/src/server/web/sandbox/context.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts)
- [packages/next/src/server/web/sandbox/sandbox.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts)
- [packages/next/src/server/app-render/app-render.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/app-render.tsx)
- [packages/next/src/server/patch-error-inspect.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts)
- [packages/next/src/server/node-environment-extensions/error-inspect.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/node-environment-extensions/error-inspect.tsx)
- [packages/next/src/next-devtools/userspace/app/forward-logs.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/forward-logs.ts)
- [packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts)
- [packages/next/src/server/web/globals.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/globals.ts)
- [packages/next/src/next-devtools/userspace/app/errors/intercept-console-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/intercept-console-error.ts)
- [packages/next/src/client/react-client-callbacks/error-boundary-callbacks.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/react-client-callbacks/error-boundary-callbacks.ts)
- [packages/next/src/server/node-environment-extensions/unhandled-rejection.external.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/node-environment-extensions/unhandled-rejection.external.tsx)
- [packages/next/src/server/web/sandbox/index.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/index.ts)
- [packages/next/src/next-devtools/userspace/app/app-dev-overlay-setup.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/app-dev-overlay-setup.ts)
- [packages/next/src/next-devtools/userspace/pages/pages-dev-overlay-setup.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/pages/pages-dev-overlay-setup.tsx)
- [packages/next/src/next-devtools/userspace/app/errors/stitched-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/stitched-error.ts)
- [packages/next/src/client/react-client-callbacks/on-recoverable-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/react-client-callbacks/on-recoverable-error.ts)
- [packages/next/src/next-devtools/userspace/app/app-dev-overlay-error-boundary.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/app-dev-overlay-error-boundary.tsx)
- [packages/next/src/client/dev/runtime-error-handler.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/dev/runtime-error-handler.ts)
- [packages/next/src/client/react-client-callbacks/report-global-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/react-client-callbacks/report-global-error.ts)
- [packages/next/src/next-devtools/userspace/app/errors/index.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/index.ts)
- [packages/next/src/client/components/unstable-rethrow.browser.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/unstable-rethrow.browser.ts)
- [packages/next/src/next-devtools/userspace/app/client-entry.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/client-entry.tsx)
- [packages/next/src/client/components/unstable-rethrow.server.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/unstable-rethrow.server.ts)
- [packages/next/src/client/components/unstable-rethrow.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/unstable-rethrow.ts)
- [packages/next/src/server/dev/node-stack-frames.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/dev/node-stack-frames.ts)
- [packages/next/src/shared/lib/turbopack/internal-error.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/turbopack/internal-error.ts)
- [packages/next/src/next-devtools/dev-overlay/container/runtime-error/index.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/dev-overlay/container/runtime-error/index.tsx)
- [packages/next/src/server/create-deduped-by-callsite-server-error-logger.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/create-deduped-by-callsite-server-error-logger.ts)
- [packages/next/src/client/components/hooks-server-context.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/hooks-server-context.ts)
- [packages/next/src/client/components/handle-isr-error.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/handle-isr-error.tsx)
## Overview
### Overview
The Edge Sandbox Context subsystem provides a controlled virtual machine execution environment for running Edge Runtime functions, middleware, and API routes within Next.js. Because Edge functions execute in a restricted environment modeled on standard Web APIs rather than full Node.js server environments, Next.js implements a specialized module context loader and V8-backed runtime using `next/dist/compiled/edge-runtime`. This setup bridges user code with isolated global bindings, simulated environment variables, polyfilled Node.js built-in modules, and resource cleanup managers.
Sources: [packages/next/src/server/web/sandbox/context.ts:30-56](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L30-L56)
To maintain strict security boundaries and API limitations, the sandbox implements controlled stubbing for unsupported Node.js features and intercepts global execution states. When developers import unsupported modules (such as `fs` or `net`), proxy wrappers dynamically throw unsupported API errors.
Sources: [packages/next/src/server/web/globals.ts:57-82](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/globals.ts#L57-L82)
Furthermore, the sandbox hooks into error stack formatting, runtime error inspection, and development overlays to ensure that execution traces inside the edge context map correctly back to source code locations.
Sources: [packages/next/src/server/patch-error-inspect.ts:350-467](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L350-L467)
```mermaid
flowchart TD
A["Runner Request"] --> B["getRuntimeContext()"]
B --> C["getModuleContext()"]
C --> D["Initialize EdgeRuntime"]
D --> E["Apply Process Polyfills & Global Bindings"]
E --> F["Evaluate Module Paths"]
F --> G["Execute Edge Handler Function"]
G --> H["FetchEventResult Response"]
```
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:72-109](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L72-L109)
---
## Module Context Management and Caching
The sandbox architecture caches initialized module contexts to avoid repeated compilation overhead across incoming requests. Module contexts are stored globally in `moduleContexts` (a `Map`) and `pendingModuleCaches` (a `Map>`). A `ModuleContext` interface combines the compiled `EdgeRuntime` instance, a map of loaded paths, and a set of warned evaluations.
Sources: [packages/next/src/server/web/sandbox/context.ts:30-58](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L30-L58)
When file changes or hot-reloads occur, `clearModuleContext(path: string)` inspects active and pending module caches. If a cached module context contains the modified file path, the entry is evicted, and associated timer resources managed by `intervalsManager` and `timeoutsManager` are purged via `.removeAll()`.
Sources: [packages/next/src/server/web/sandbox/context.ts:78-98](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L78-L98)
Similarly, `clearAllModuleContexts()` resets all active timers and clears both caches completely.
Sources: [packages/next/src/server/web/sandbox/context.ts:63-68](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L63-L68)
```mermaid
flowchart LR
A["clearModuleContext(path)"] --> B["intervalsManager.removeAll()"]
B --> C["timeoutsManager.removeAll()"]
C --> D{"Check moduleContexts"}
D -->|Match path| E["moduleContexts.delete(key)"]
D -->|No match| F{"Check pendingModuleCaches"}
F -->|Match path| G["pendingModuleCaches.delete(key)"]
```
Sources: [packages/next/src/server/web/sandbox/context.ts:78-98](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L78-L98)
---
## Environment Variables and Process Polyfilling
Edge runtime functions do not have direct access to the host Node.js `process` object. To provide seamless compatibility with standard environment access patterns, Next.js constructs a specialized process polyfill using `createProcessPolyfill(env)`.
Sources: [packages/next/src/server/web/sandbox/context.ts:137-140](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L137-L140)
The polyfill merges `process.env` with injected custom environments via `buildEnvironmentVariablesFrom(injectedEnvironments)`, explicitly appending `NEXT_RUNTIME: 'edge'`.
Sources: [packages/next/src/server/web/sandbox/context.ts:118-127](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L118-L127)
For all other properties on the native `process` object (excluding `env`), `Object.defineProperty` is used to intercept property access. If user code attempts to invoke a property that is a function (e.g., `process.nextTick` or `process.cwd()`), a getter throws an unsupported API error referencing `process.${key}`.
Sources: [packages/next/src/server/web/sandbox/context.ts:141-158](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L141-L158)
Properties can also be dynamically overridden by assigning values to `processPolyfill`.
Sources: [packages/next/src/server/web/sandbox/context.ts:153-155](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L153-L155)
| Process Property / API | Polyfill Behavior | Purpose / Restriction |
|-----------------------|-------------------|----------------------|
| `process.env` | Merged via `buildEnvironmentVariables` | Exposes runtime environment variables plus `NEXT_RUNTIME: 'edge'` |
| Function properties | Getter returns function throwing unsupported API error | Prevents unauthorized execution of Node.js-only process methods |
| Non-function properties | Returns `undefined` unless overridden | Safeguards against undefined host state leakage |
Sources: [packages/next/src/server/web/sandbox/context.ts:118-160](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L118-L160)
---
## Unsupported Module Stubs and API Guards
When user code running inside the Edge Sandbox imports or invokes forbidden Node.js APIs or built-in modules, Next.js enforces strict restrictions via `throwUnsupportedAPIError` and `__import_unsupported`.
Sources: [packages/next/src/server/web/sandbox/context.ts:129-135](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L129-L135), [packages/next/src/server/web/globals.ts:57-61](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/globals.ts#L57-L61)
The `__import_unsupported` function returns a specialized Proxy object. Any attempt to access properties (other than `.then`), construct instances, or invoke the proxy function triggers an immediate error citing the unsupported Node.js module name.
Sources: [packages/next/src/server/web/globals.ts:63-82](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/globals.ts#L63-L82)
Similarly, `addStub` attaches property getters to the `EdgeRuntime` context that invoke `throwUnsupportedAPIError(name)` when accessed.
Sources: [packages/next/src/server/web/sandbox/context.ts:162-171](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L162-L171)
> [!CAUTION]
> Importing restricted Node.js core modules (such as `fs`, `net`, or `child_process`) in Edge runtime files will throw an error at runtime unless guarded by conditional environment checks.
Sources: [packages/next/src/server/web/globals.ts:57-61](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/globals.ts#L57-L61)
---
## Runtime Execution Pipeline and Request Handling
The execution lifecycle of an Edge handler is orchestrated by the `run` function in `sandbox.ts`, wrapped with `withTaggedErrors` in development mode to decorate errors with `edge-server` compiler tags.
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:49-70](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L49-L70), [packages/next/src/server/web/sandbox/sandbox.ts:111-163](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L111-L163)
The execution sequence proceeds through the following steps:
1. `getRuntimeContext(params)` retrieves or initializes the module context, exposes shared caches (`__incrementalCache`, `__serverComponentsHmrCache`, `NEXT_CLIENT_ASSET_SUFFIX`), and evaluates requested module paths into the V8 context.
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:72-109](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L72-L109)
2. Module resolution extracts the default export handler from `runtime.context._ENTRIES`.
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:114-116](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L114-L116)
3. Request body streams are cloned if the HTTP method is outside `['HEAD', 'GET']`.
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:118-120](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L118-L120)
4. Context wrapping runs the handler inside `edgeSandboxNextRequestContext` and `requestStore` asynchronous local storage providers, mapping headers and setting up request metadata.
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:134-156](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L134-L156)
```mermaid
sequenceDiagram
participant Client as Client Request
participant Run as run() / withTaggedErrors
participant Context as getRuntimeContext()
participant Runtime as EdgeRuntime Sandbox
participant Handler as Edge Handler
Client->>Run: Invoke runner with params & request data
Run->>Context: getRuntimeContext(params)
Context->>Runtime: Evaluate module paths & bind globals
Runtime-->>Context: Initialized runtime instance
Context-->>Run: Ready runtime
Run->>Handler: Execute middleware/edge function
Handler-->>Run: FetchEventResult (Response + WaitUntil)
Run->>Client: Return sanitized response
```
Sources: [packages/next/src/server/web/sandbox/sandbox.ts:72-163](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/sandbox.ts#L72-L163)
---
## Error Inspection and Stack Frame Patching
To ensure stack traces originating inside the Edge sandbox or Node.js server environments provide accurate source maps and developer-friendly formatting, Next.js implements error inspection patching via `packages/next/src/server/patch-error-inspect.ts`.
Sources: [packages/next/src/server/patch-error-inspect.ts:350-542](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L350-L542)
The error inspection subsystem overrides `Error.prepareStackTrace` with `prepareUnsourcemappedStackTrace` and attaches custom inspection symbols (`nodejs.util.inspect.custom` for Node.js environments and `edge-runtime.inspect.custom` for edge-lite runtimes).
Sources: [packages/next/src/server/patch-error-inspect.ts:502-540](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L502-L540)
During error serialization or inspection, `parseAndSourceMap` extracts `error.stack`, strips internal React stack frames past `react_stack_bottom_frame` or `react-stack-bottom-frame`, and parses stack frames.
Sources: [packages/next/src/server/patch-error-inspect.ts:350-376](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L350-L376)
It resolves sourcemapped frames using `getSourcemappedFrameIfPossible` against cached source maps, filters anonymous sandwich frames, and rebuilds formatted stacks.
Sources: [packages/next/src/server/patch-error-inspect.ts:398-421](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L398-L421)
```mermaid
flowchart TD
A["Error Thrown / Inspected"] --> B["Custom inspect symbol triggered"] --> C["parseAndSourceMap()"]
C --> D["Extract stack & truncate internal frames"] --> E["Parse stack frames"]
E --> F["Map original positions via source maps"] --> G["Filter ignore-listed sandwich frames"]
G --> H["Rebuild formatted stack with code frames"] --> I["Return decorated error string"]
```
Sources: [packages/next/src/server/patch-error-inspect.ts:350-467](https://github.com/blade47/next.js/blob/main/packages/next/src/server/patch-error-inspect.ts#L350-L467)
---
## Log Forwarding and Dev Overlay Integration
Development errors and console logs captured within edge and server runtimes are forwarded to the client browser or development overlay via `packages/next/src/next-devtools/userspace/app/forward-logs.ts` and `use-error-handler.ts`.
Sources: [packages/next/src/next-devtools/userspace/app/forward-logs.ts:88-130](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/forward-logs.ts#L88-L130), [packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts:22-46](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts#L22-L46)
The logging subsystem maintains a `logQueue` that batches log entries (`any-logged-error`, `console`, `formatted-error`) and schedules non-blocking transmission (`scheduleLogSend`) using `requestAnimationFrame` and `setTimeout` (`afterThisFrame`).
Sources: [packages/next/src/next-devtools/userspace/app/forward-logs.ts:88-130](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/forward-logs.ts#L88-L130)
When unhandled errors or rejections occur, `forwardUnhandledError` captures uncaught errors, extracts owner stacks using `getErrorStackWithOwnerStack` (backed by React owner stack tracing in `stitched-error.ts`), and queues log entries with source type designations.
Sources: [packages/next/src/next-devtools/userspace/app/forward-logs.ts:373-383](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/forward-logs.ts#L373-L383)
Additionally, `handleConsoleError` intercepts console error arguments, parses environment names, wraps errors using `createConsoleError`, and dispatches them asynchronously through microtask queues.
Sources: [packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts:22-46](https://github.com/blade47/next.js/blob/main/packages/next/src/next-devtools/userspace/app/errors/use-error-handler.ts#L22-L46)
---
## Native Module Mapping and WebAssembly Loading
The sandbox provides explicit polyfills for supported Node.js core modules through `NativeModuleMap`, granting safe subset access to standard APIs.
Sources: [packages/next/src/server/web/sandbox/context.ts:191-214](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L191-L214)
Supported modules mapped in `NativeModuleMap` include `'node:buffer'`, `'node:events'`, and `'node:async_hooks'`.
Sources: [packages/next/src/server/web/sandbox/context.ts:191-214](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L191-L214)
Additionally, WebAssembly bindings associated with edge functions are compiled asynchronously into `WebAssembly.Module` instances via `loadWasm`, reading asset files from disk and mapping them by binding name.
Sources: [packages/next/src/server/web/sandbox/context.ts:100-116](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L100-L116)
| Native Module Key | Exposed APIs / Exports | Underlying Implementation Source |
|-------------------|------------------------|----------------------------------|
| `node:buffer` | constants, kMaxLength, kStringMaxLength, Buffer, SlowBuffer | BufferImplementation (`node:buffer`) |
| `node:events` | EventEmitter, captureRejectionSymbol, defaultMaxListeners, errorMonitor, listenerCount, on, once | EventsImplementation (`node:events`) |
| `node:async_hooks` | AsyncLocalStorage, AsyncResource | AsyncHooksImplementation (`node:async_hooks`) |
Sources: [packages/next/src/server/web/sandbox/context.ts:191-214](https://github.com/blade47/next.js/blob/main/packages/next/src/server/web/sandbox/context.ts#L191-L214)
## Related
- [Web Spec Adapters](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/edge-and-sandbox/web-spec-adapters)
- [Middleware Execution](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/edge-and-sandbox/middleware-execution)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.