vitejs/vite · error · Error

Vite Internal Error: registerMissingImport is not supported

Error message

Vite Internal Error: registerMissingImport is not supported in dev ${environment.name}

What it means

`createExplicitDepsOptimizer` builds a limited optimizer for environments (e.g. SSR/dev environments without a scanner) whose `registerMissingImport` is a hard error — these environments optimize only the explicitly-listed deps and cannot dynamically register a new import discovered at runtime. The throw at optimizer.ts:764 is prefixed 'Vite Internal Error' because the call should never reach it under normal use; it indicates the environment's optimizer type doesn't support lazy registration.

Source

Thrown at packages/vite/src/node/optimizer/optimizer.ts:764

      debouncedProcessing(0)
    }
  }

  return depsOptimizer
}

export function createExplicitDepsOptimizer(
  environment: DevEnvironment,
): DepsOptimizer {
  const depsOptimizer = {
    metadata: initDepsOptimizerMetadata(environment),
    isOptimizedDepFile: createIsOptimizedDepFile(environment),
    isOptimizedDepUrl: createIsOptimizedDepUrl(environment),
    getOptimizedDepId: (depInfo: OptimizedDepInfo) =>
      `${depInfo.file}?v=${depInfo.browserHash}`,

    registerMissingImport: () => {
      throw new Error(
        `Vite Internal Error: registerMissingImport is not supported in dev ${environment.name}`,
      )
    },
    init,
    // noop, there is no scanning during dev SSR
    // the optimizer blocks the server start
    run: () => {},

    close: async () => {},
    options: environment.config.optimizeDeps,
  }

  let inited = false
  async function init() {
    if (inited) return
    inited = true

    depsOptimizer.metadata = await optimizeExplicitEnvironmentDeps(environment)

View on GitHub (pinned to 89620f09af)

Solutions

1. Don't call `registerMissingImport` on explicit-only optimizers — pre-list deps in `optimizeDeps.include` instead.
2. If you need lazy registration, use a full dev environment with a scanner (the default client environment), not the explicit optimizer.
3. Update the framework/Vite version — environment APIs are evolving and this contract has changed.
4. Report it as a Vite internal bug if you're not calling the API yourself (the message says so).

// Before calling registerMissingImport, verify the optimizer supports it:
function supportsLazyRegistration(optimizer: DepsOptimizer): boolean {
  return typeof optimizer.registerMissingImport === 'function'
    && !String(optimizer.registerMissingImport).includes('not supported')
}

function isFullOptimizer(o: DepsOptimizer): boolean {
  // explicit optimizer's registerMissingImport is a throwing arrow fn
  return !/not supported/.test(o.registerMissingImport.toString())
}

When it happens

Trigger: An internal Vite code path (or custom Environment API consumer) calls `registerMissingImport` on an optimizer created by `createExplicitDepsOptimizer` — i.e. an environment that only supports explicit dep optimization.

Common situations: Using the experimental Environment API with a custom environment that doesn't run scanning; a Vite plugin or framework integration calling the optimizer's `registerMissingImport` for an SSR environment; version mismatch between Vite core and a framework's environment plugin.

Related errors

• ${this.name} environment.pluginContainer called before initi
• Can not commit a Deps Optimization run as it was cancelled
• The build was canceled
• [module runner] Dynamic access of "import.meta.env" is not s
• [module runner] "import.meta.resolve" is not supported.

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