`server.close()` in JavaScript API hangs forever

[nicomouss]

Describe the bug

From Vite 8.1.4 onward, server.close() can hang forever and never resolve.

Which means that using Vite JavaScript API in Vitest leads to tests timing-out because of that.

Reproduction

https://github.com/nicomouss/Vite-JavascriptAPI-server-close-hanging

Steps to reproduce

The linked repo implements a Vitest test reproducing the error.

Please follow the instructions given in the repo.

The test fails because of the server.close() instruction:

onTestFinished(async () => {
  await server.close(); // This never resolves, leading to the test timing out
});

The issue has been introduced from Vite 8.1.4.
Everything works fine for versions 8.1.3 and below.

System Info

System:
    OS: macOS 15.7.3
    CPU: (8) arm64 Apple M3
    Memory: 2.43 GB / 16.00 GB
  Binaries:
    Node: 24.17.0
    pnpm: 11.8.0
  npmPackages:
    vite: ^8.1.4 => 8.1.4

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Vite issue and not a framework-specific issue. For example, if it's a Vue SFC related bug, it should likely be reported to vuejs/core instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[sapphi-red]

I guess this is related to #22852. That PR made the optimizer not to run until the server.listen is called. server.close might be hanging because it internally it might be waiting for the optimizer.

[nicomouss]

@sapphi-red Thanks for your feedback.

Indeed, when disabling Vite optimization in the reproduction repo, everything works fine:

const server = await createServer({
    // ...
    optimizeDeps: {
        noDiscovery: true
    }
    // ...
});

If using Vite dev server with server.transformRequest(...) instructions to programmatically query URLs without the browser/http stuff involved (for example to test a custom Vite plugin), there might be no need of Vite optimization anyway.

Disabling the optimizer can thus be a solution in such scenario, for the time being, to circumvent the issue.

[shleder]

The version-specific behavior here seems like the kind of reproduction where exact package/runtime/command context matters more than a long environment description.

I’m validating a small OSS tool that creates a local sanitized receipt with runtime, dependency-file hashes, Git context, the command and its result.

Would having a receipt like that with the initial report have made this regression easier to verify?

[santusht06]

Can confirm the exact mechanism behind this deadlock:

1. When server.transformRequest(...) encounters a bare specifier without server.listen() being called, it registers the discovered dep with info.processing (a pending Promise).
2. The import is rewritten to /.vite/deps/..., and when loaded, vite:optimized-deps plugin's load hook executes await info.processing in packages/vite/src/node/plugins/optimizedDeps.ts.
3. Because server.listen() was never called (following fix(optimizer): avoid optimizer run for transform request before init #22852), depsOptimizer.init() never runs and the optimizer never starts, leaving info.processing pending indefinitely.
4. EnvironmentPluginContainer.load tracks this via this.handleHookPromise(...), adding the pending load promise to this._processesing.
5. When server.close() is called, pluginContainer.close() executes await Promise.allSettled(Array.from(this._processesing)), which blocks forever on the unfulfilled info.processing promise.

Suggested fix: In depsOptimizer.close(), ensure all pending info.processing promises are settled/cancelled, or check for closed state in optimizedDeps.load().

[zhouzhiouhub]

"I've reviewed both #23155 and #23347. Here's my analysis:"

#23155 resolves the pending processing promise directly in close(). It's a minimal, low-risk fix that addresses the immediate hang. The test case is thorough and verifies the promise state transitions.

#23347 takes a broader approach: it adds resolveEnqueuedProcessingPromises() and depOptimizationProcessing.resolve() in close(), but also introduces an isClosed guard in the optimizedDeps plugin's load hook (if (depsOptimizer?.isClosed?.()) return null). This prevents any future load attempts from hanging after shutdown.

My take: #23347 is more robust because it not only fixes the hang but also protects against similar issues in other entry points. The additional guard doesn't seem to introduce side effects since isClosed is only checked during shutdown.

Suggestion: The test from #23155 is more detailed and could be integrated into #23347. I'd be happy to help refine or combine them if the team prefers a single PR.