Profiles·Public

vite

semver>=5.0.0 <9.0.0postconditions17functions10last verified2026-04-18coverage score100%

Postconditions — what we check

build · build-failure
error
Whenbundler encounters a parse error, unresolved import, plugin error, or invalid configuration
ThrowsRollupError (re-thrown from rolldown/rollup) with fields: .code (error category), .plugin (plugin name if applicable), .id (file that caused the error), .loc ({ file, line, column }), .frame (code context snippet), .message (enhanced with file and location info)
Required handlingCaller MUST wrap build() in try/catch (or .catch()) to handle build failures. Unhandled rejections cause the Node.js process to emit an unhandledRejection event and exit non-zero in CI environments. The RollupError.message includes enhanced context (plugin name, file path, code frame) and should be logged before exiting. Callers MUST NOT attempt to use the return value if the promise rejects. Note: bundle cleanup (bundle.close()) is handled internally by vite — callers do not need to close anything.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
createServer · server-creation-failure
error
Whenport is in use (EADDRINUSE), HTTPS certificate files not found, plugin initialization fails, or config was resolved for 'build' command
ThrowsOS-level Error (EADDRINUSE, ENOENT, EACCES) or RollupError from plugin hooks, or Error with message "Config was resolved for a 'build', expected a 'serve' command."
Required handlingCaller MUST wrap createServer() in try/catch. If server was partially created before the error, caller SHOULD call server.close() for cleanup. In long-running processes, caller MUST also register process.on('SIGTERM') and process.on('SIGINT') handlers to call server.close() to free the port and file watchers.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
createServer · config-reuse-forbidden
error
Whensame ResolvedConfig object passed to more than one createServer() call
ThrowsError: There is already a server associated with the config.
Required handlingEach createServer() call MUST use a fresh InlineConfig (plain object), not a previously resolved config. Do not cache and reuse ResolvedConfig across calls.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
preview · preview-server-failure
error
Whenport is in use or configuration is invalid
ThrowsOS-level Error (EADDRINUSE, EACCES)
Required handlingCaller MUST wrap preview() in try/catch. Caller MUST call server.close() in a finally block or process signal handler to release the port.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
server.listen · server-listen-middleware-mode-forbidden
error
Whenserver.middlewareMode is true (Vite is used as middleware in another HTTP framework)
ThrowsError: "Cannot call server.listen in middleware mode." The underlying httpServer is null in middleware mode, so listen() always throws.
Required handlingCaller MUST check server.config.server.middlewareMode before calling listen(). In middleware mode, the parent framework (Express, Fastify, etc.) controls the server lifecycle — do NOT call server.listen() at all. The Vite dev server integrates via server.middlewares (a connect app).
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2][4]
server.listen · server-listen-port-conflict
error
Whenconfigured port is already in use by another process AND server.strictPort is true
ThrowsError: "Port N is already in use" — thrown by httpServerStart() when strictPort is true and the port cannot be bound. When strictPort is false (default), Vite auto-increments the port up to 65535 before throwing "No available ports found between M and 65535".
Required handlingCaller MUST wrap server.listen() in try/catch. If port conflicts are expected (e.g., multiple dev servers), set strictPort: false (the default) and check server.resolvedUrls after listen() returns to get the actual port used. Caller MUST also call server.close() in a finally block or process signal handler to free resources on any failure.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[4][5]
server.close · server-close-not-awaited
warning
Whenserver.close() is called but the returned Promise is not awaited before process exit (e.g., in a fire-and-forget call)
ThrowsDoes not throw, but: if close() completes after process.exit() is called, file watchers and WebSocket connections may not be properly terminated, causing port occupation on next start and orphaned chokidar processes.
Required handlingCaller MUST await server.close() before allowing the process to exit. The correct pattern is: process.on('SIGTERM', async () => { await server.close(); process.exit(0); }); Note: when NOT in middleware mode, Vite automatically registers SIGTERM/SIGINT handlers that call server.close(). In middleware mode, callers are responsible for calling server.close() themselves.
costlowin prodsilent failureusers seedegraded performancevisibilitysilent
Sources[2][4]
server.restart · server-restart-port-conflict
error
WhenPort is taken by a different process during the restart window (rare race condition when the old server releases and the new server tries to bind)
ThrowsError: "Port N is already in use" — propagated from the internal listen() call during restart. The old server has already been closed at this point, so the dev server is completely down until restart() resolves or rejects.
Required handlingCaller MUST wrap server.restart() in try/catch. If restart fails, the dev server is in a closed state and a new createServer() + listen() sequence is required to recover. Log the error and surface it to the developer immediately.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[4][2]
resolveConfig · resolveconfig-config-hook-throws
error
WhenA vite plugin's configHook or configResolvedHook throws an error during the plugin resolution phase (e.g., plugin validates config and rejects it)
ThrowsAny Error thrown by the plugin — propagated directly. Error type, message, and shape depend on the plugin. Common pattern: Error with message describing misconfiguration.
Required handlingCaller MUST wrap resolveConfig() in try/catch. For tools building on top of Vite, display the plugin name (e.g., via error.plugin or by scanning the error message) to help users identify which plugin caused the failure.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6][7]
resolveConfig · resolveconfig-environments-stripped
error
WhenA plugin's config hook removes or nullifies the required client/ssr environment configurations (config.environments.client is falsy after plugin hooks run)
ThrowsError: "Required environments configuration were stripped out in the config hook" Thrown at the end of resolveConfig() as a safety check.
Required handlingPlugin authors MUST NOT delete config.environments.client or config.environments.ssr from the resolved config. Callers of resolveConfig() who see this error should audit their plugin list for plugins that mutate the environments object destructively.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6]
loadConfigFromFile · loadconfig-invalid-loader
error
WhenconfigLoader parameter is not one of 'bundle', 'runner', or 'native'
ThrowsError: "Unsupported configLoader: X. Accepted values are 'bundle', 'runner', and 'native'." Thrown synchronously before any file I/O.
Required handlingCallers providing a dynamic configLoader value MUST validate it against ['bundle', 'runner', 'native'] before calling loadConfigFromFile(). This is typically a programming error, not a runtime failure.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6]
loadConfigFromFile · loadconfig-not-an-object
error
WhenThe config file's default export is not an object (e.g., exports a string, number, or array instead of a config object)
ThrowsError: "config must export or return an object." Thrown after the config file is loaded and its export is evaluated.
Required handlingConfig files MUST export a plain object or a function returning a plain object (or Promise<object>). Callers of loadConfigFromFile() MUST wrap it in try/catch and report the config file path to help users locate the invalid export.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6][8]
loadConfigFromFile · loadconfig-esm-only-dependency
error
WhenConfig file uses require() to load an ESM-only package (common in .cjs config files trying to import ESM-only Vite plugins)
ThrowsError: "Failed to resolve X. This package is ESM only but it was tried to load by `require`. See https://vite.dev/guide/troubleshooting.html#this-package-is-esm-only" Thrown during the rolldown bundling phase of the config file.
Required handlingCallers MUST wrap loadConfigFromFile() in try/catch. For tooling, surface the error message directly — it includes the package name and a documentation link. The fix is to use .mjs or .ts config files instead of .cjs when depending on ESM-only plugins.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6][9]
loadConfigFromFile · loadconfig-tsx-jiti-missing
error
WhenConfig file is a TypeScript file (.ts) and neither 'tsx' nor 'jiti' is installed (required for TypeScript config execution in 'runner' configLoader mode)
ThrowsError: "'tsx' or 'jiti' is required for the TypeScript configuration files. Make sure it is installed" Only thrown in 'runner' mode — the default 'bundle' mode handles TS via rolldown+oxc.
Required handlingWhen using configLoader: 'runner', ensure 'tsx' or 'jiti' is in devDependencies. Callers MUST wrap in try/catch and surface the missing dependency name to the user.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6][8]
createBuilder · createbuilder-config-resolution-failure
error
WhenConfig file fails to load (syntax errors, missing exports, plugin hook throws, or invalid environment configuration) — same failure surface as resolveConfig()
ThrowsAny Error from the config resolution chain — typically Error with message from the failing plugin or config file. Error types depend on what the config file or plugins throw.
Required handlingCaller MUST wrap createBuilder() in try/catch. This is typically used in build scripts where the process should exit non-zero on failure. Log the full error (including stack) and process.exit(1) to ensure CI pipelines detect the failure.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[10][11]
createBuilder · createbuilder-environment-init-failure
error
WhenA build environment's init() method throws — e.g., a plugin's buildStart hook rejects, or the environment configuration is invalid
ThrowsAny Error from the environment init chain. Multiple environments are initialized in parallel via Promise.all(), so the first rejection is surfaced.
Required handlingCaller MUST wrap createBuilder() in try/catch. Since environments init in parallel, failures from any environment are surfaced. The builder is NOT usable if createBuilder() rejects — do not attempt partial builds.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[10][11]
transformWithOxc · transformwithoxc-parse-error
error
WhenInput code has TypeScript/JavaScript syntax errors, invalid JSX, or unsupported language features for the inferred file extension
ThrowsError with message: "Transform failed with N error(s):\n[error details]" The thrown Error object has an .errors property (array of OxcTransformError) with per-error details including the code location and description. The .errors array is accessible via Object.defineProperty (enumerable: true).
Required handlingCaller MUST wrap transformWithOxc() in try/catch. To display useful errors, access error.errors (the OxcTransformError array) — each item has location info. The error.message contains a formatted summary of all errors (up to 5 shown). Callers building Vite plugins SHOULD re-throw with the original error to allow Vite's error overlay to display it correctly.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[12][13]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

Need a different package?

Request a profile