{"record":{"id":"dca8103fbc4e5e73","repo":"vitejs/vite","slug":"fetchabledevenvironment-requires-a-handlerequest","errorCode":null,"errorMessage":"FetchableDevEnvironment requires a `handleRequest` method during initialisation.","messagePattern":"FetchableDevEnvironment requires a `handleRequest` method during initialisation\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vite/src/node/server/environments/fetchableEnvironments.ts","lineNumber":22,"sourceCode":"import type { Environment } from '../../environment'\n\nexport interface FetchableDevEnvironmentContext extends DevEnvironmentContext {\n  handleRequest(request: Request): Promise<Response> | Response\n}\n\nexport function createFetchableDevEnvironment(\n  name: string,\n  config: ResolvedConfig,\n  context: FetchableDevEnvironmentContext,\n): FetchableDevEnvironment {\n  if (typeof Request === 'undefined' || typeof Response === 'undefined') {\n    throw new TypeError(\n      'FetchableDevEnvironment requires a global `Request` and `Response` object.',\n    )\n  }\n\n  if (!context.handleRequest) {\n    throw new TypeError(\n      'FetchableDevEnvironment requires a `handleRequest` method during initialisation.',\n    )\n  }\n\n  return new FetchableDevEnvironment(name, config, context)\n}\n\nexport function isFetchableDevEnvironment(\n  environment: Environment,\n): environment is FetchableDevEnvironment {\n  return environment instanceof FetchableDevEnvironment\n}\n\nclass FetchableDevEnvironment extends DevEnvironment {\n  private _handleRequest: (request: Request) => Promise<Response> | Response\n\n  constructor(\n    name: string,","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/vitejs/vite/blob/b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab/packages/vite/src/node/server/environments/fetchableEnvironments.ts#L4-L40","documentation":"Thrown by createFetchableDevEnvironment() when the provided context object has no handleRequest method. A FetchableDevEnvironment models an environment that can be driven by the Fetch API (Request in, Response out), so a request handler is mandatory — the environment has no default behavior for serving requests. Without it, dispatchFetch() would have nothing to call.","triggerScenarios":"Calling createFetchableDevEnvironment(name, config, context) where context.handleRequest is undefined or not a function (e.g. omitted from the context object, or misspelled as handler/handle). The check is a falsy test on context.handleRequest at fetchableEnvironments.ts:21.","commonSituations":"Building a custom fetch-based dev environment (e.g. for a framework SSR runner like a Cloudflare/Partytown environment) and forgetting to wire the request handler. Migrating from an older DevEnvironment API where handleRequest was optional. Spreading a base context that did not include handleRequest.","solutions":["Provide a handleRequest(request: Request): Response | Promise<Response> function in the context passed to createFetchableDevEnvironment.","Check the spelling — it must be exactly handleRequest, not handle or on_request.","Ensure the handler actually returns a Response (a fetch() result, new Response(...), etc.), not a plain object."],"exampleFix":"// before\ncreateFetchableDevEnvironment('ssr', config, { modulesRunner: runner })\n// after\ncreateFetchableDevEnvironment('ssr', config, {\n  async handleRequest(request: Request): Promise<Response> {\n    return new Response('ok')\n  },\n})","handlingStrategy":"validation","validationCode":"if (typeof context.handleRequest !== 'function') {\n  throw new Error('context.handleRequest must be a function returning a Response')\n}\nconst env = createFetchableDevEnvironment(name, config, context)","typeGuard":"function hasHandleRequest(c: DevEnvironmentContext): c is FetchableDevEnvironmentContext {\n  return typeof (c as any).handleRequest === 'function'\n}","tryCatchPattern":null,"preventionTips":["Type the context parameter as FetchableDevEnvironmentContext so TypeScript enforces handleRequest at compile time.","Reuse a shared factory wrapper that always injects handleRequest."],"tags":["fetchable-environment","configuration","initialization"],"backgroundTag":null,"analyzedSha":"b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab","analyzedAt":"2026-08-11T11:49:19.515Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}