vitejs/vite · error · Error

fetchModule is disabled in this environment

Error message

fetchModule is disabled in this environment

What it means

DevEnvironment registers a fetchModule invoke handler on its hot channel. If context.disableFetchModule is true, the handler throws instead of running fetchModule. This lets a environment opt out of serving transformed module source over its transport (used by some RTE/SSR setups that do not expose modules to clients).

Solutions

1. Do not call fetchModule on environments where disableFetchModule is set; check the context before calling.
2. Construct the environment with disableFetchModule: false (or omit it) if the consumer needs module source.
3. Route module fetching through an environment that exposes it (e.g. the client/SSR dev environment).
4. If you control the transport, avoid emitting the fetchModule invoke for disabled environments.

Example fix

// before
const env = new DevEnvironment('x', config, { disableFetchModule: true, ... })
await env.fetchModule(id)
// after
const env = new DevEnvironment('x', config, { disableFetchModule: false, ... })
await env.fetchModule(id)

function assertFetchModuleEnabled(context) {
  if (context.disableFetchModule) throw new Error('fetchModule is disabled for this environment')
}
assertFetchModuleEnabled(context)

function canFetchModule(context): boolean {
  return !context.disableFetchModule
}

try {
  return await env.fetchModule(id, importer, opts)
} catch (e) {
  if (/fetchModule is disabled/.test(e.message)) return null // graceful skip
  throw e
}

When it happens

Trigger: A consumer calls environment.fetchModule (or the hot channel invokes 'fetchModule') on an environment whose DevEnvironmentContext was created with disableFetchModule: true. Common when a runtime tries to pull module source from an environment configured not to serve it.

Common situations: Custom runtime/transport adapters calling fetchModule indiscriminately, or copying context options from an SSR environment (which may disable fetchModule) into a context that is then queried for modules.

Related errors

• Environment " " is not defined in the config.
• Cannot call server.listen in middleware mode.
• Cannot print server URLs before server is listening.
• Cannot print server URLs before server.listen is called.
• Cannot print server URLs in middleware mode.

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/621e03027622ea77. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/server/environment.ts:161

    this._crawlEndFinder = setupOnCrawlEnd()

    this._remoteRunnerOptions = context.remoteRunner ?? {}
    this._skipFsCheck = !!(
      context.transport &&
      !(isWebSocketServer in context.transport) &&
      context.transport.skipFsCheck
    )

    this.hot = context.transport
      ? isWebSocketServer in context.transport
        ? context.transport
        : normalizeHotChannel(context.transport, context.hot)
      : normalizeHotChannel({}, context.hot)

    this.hot.setInvokeHandler({
      fetchModule: (id, importer, options) => {
        if (context.disableFetchModule) {
          throw new Error('fetchModule is disabled in this environment')
        }
        return this.fetchModule(id, importer, options)
      },
      getBuiltins: async () => {
        return this.config.resolve.builtins.map((builtin) =>
          typeof builtin === 'string'
            ? { type: 'string', value: builtin }
            : { type: 'RegExp', source: builtin.source, flags: builtin.flags },
        )
      },
    })

    this.hot.on(
      'vite:invalidate',
      ({ path, message, firstInvalidatedBy }, client) => {
        this.invalidateModule(
          {
            path,

View on GitHub (pinned to b4d66fee14)