vitejs/vite · error · TypeError

FetchableDevEnvironment `dispatchFetch` must receive a `Requ

Error message

FetchableDevEnvironment `dispatchFetch` must receive a `Request` object.

What it means

FetchableDevEnvironment.dispatchFetch at fetchableEnvironments.ts:50 asserts that its argument is an instance of the global Request. Passing a plain object, a string URL, or a Request-like duck-typed value throws a TypeError before the request is dispatched to handleRequest.

Source

Thrown at packages/vite/src/node/server/environments/fetchableEnvironments.ts:50

): environment is FetchableDevEnvironment {
  return environment instanceof FetchableDevEnvironment
}

class FetchableDevEnvironment extends DevEnvironment {
  private _handleRequest: (request: Request) => Promise<Response> | Response

  constructor(
    name: string,
    config: ResolvedConfig,
    context: FetchableDevEnvironmentContext,
  ) {
    super(name, config, context)
    this._handleRequest = context.handleRequest
  }

  public async dispatchFetch(request: Request): Promise<Response> {
    if (!(request instanceof Request)) {
      throw new TypeError(
        'FetchableDevEnvironment `dispatchFetch` must receive a `Request` object.',
      )
    }
    const response = await this._handleRequest(request)
    if (!(response instanceof Response)) {
      throw new TypeError(
        'FetchableDevEnvironment `context.handleRequest` must return a `Response` object.',
      )
    }
    return response
  }
}

export type { FetchableDevEnvironment }

View on GitHub (pinned to 89620f09af)

Solutions

1. Always pass new Request(input, init) constructed from the global Request into dispatchFetch.
2. If you hold a different Request class, rebuild the request via new globalThis.Request(otherRequest.url, otherRequest) before dispatch.
3. Make sure there is exactly one Request constructor in the realm (avoid mixing undici's Request with the global under Node >= 18).

Example fix

// before
await env.dispatchFetch({ url: '/path', method: 'GET' })

// after
await env.dispatchFetch(new Request('https://example/path'))

function assertRequest(value: unknown) {
  if (!(value instanceof Request)) {
    throw new TypeError('dispatchFetch requires a global Request instance')
  }
}

function isRequest(value: unknown): value is Request {
  return typeof Request !== 'undefined' && value instanceof Request
}

When it happens

Trigger: Calling env.dispatchFetch({ url }) or dispatchFetch(url) instead of dispatchFetch(new Request(url)); frameworks that construct request-shaped objects without the Request constructor; a polyfilled Request class that is not the same constructor as the global one dispatchFetch checks against.

Common situations: Adapter code that hand-rolls request objects; multiple Request constructors in play (undici vs global vs polyfill) so instanceof fails; tests passing plain objects.

Related errors

• FetchableDevEnvironment `context.handleRequest` must return
• FetchableDevEnvironment requires a `handleRequest` method du
• Invalid environment name "${name}". Environment names must o
• Required environments configuration were stripped out in the
• FetchableDevEnvironment requires a global `Request` and `Res

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