Vite failed to scan dependencies: unwanted HTML entries

TL;DR#

When Failed to scan for dependencies from entries lists generated documentation HTML and the error below it points into that documentation, restrict optimizeDeps.entries to the application's actual HTML entries. Do this only when the extra HTML is not part of the app. The heading alone does not diagnose the problem: an application syntax error, an unresolved import or an older esbuild service failure needs its own repair. A narrower scan must not conceal a page that users really need.

Read past the entry list before choosing a fix#

The Stack Overflow report behind this error contains the scan heading followed by an esbuild service failure. It does not establish the cause of that process failure. Reinstalling dependencies had not resolved it, and the answers do not provide a verified repair for that particular machine.

Its first answer links to a Vite maintainer discussion about scan entries. That discussion describes a narrower, actionable case: Vite includes generated documentation HTML as scan roots, including files the developer had put in Git's ignore list. The maintainer points to the diagnostic after the list and explains how to specify the intended entries. That is the case reproduced below, rather than a claim that all failures sharing this heading have the same cause.

The exact heading is:

Failed to scan for dependencies from entries:

Treat the paths immediately below it as starting points. They do not necessarily identify the file with the defect. The subsequent diagnostic can point into a script imported from an entry, or into an inline module inside another HTML file. Preserve that part of the terminal output when reporting the problem; copying only the heading removes the evidence needed to choose a remedy.

Why Git's ignore list did not protect the documentation#

Vite's dependency optimisation options describe default discovery across HTML files in the project, with specific built-in exclusions. Git tracking rules are a different mechanism. A file can be absent from the Git index and still exist on disk where Vite discovers it.

The current scanner implementation also shows why the message is easy to misread. When scanning fails, Vite prefixes the underlying exception with the entry list. It does not replace the exception with a diagnosis. This wrapper remains present in Vite 8.3.5, where the scan runs through Rolldown rather than the esbuild service shown in the older question.

This distinction matters during upgrades. A search result describing an esbuild executable does not necessarily apply to a project whose failing stack goes through Rolldown. First identify the installed Vite version and read the actual child diagnostic. Changing a React component or adding a React plugin without that evidence is unrelated to the reproduced entry-selection problem.

Reproduce the unwanted entry on current Vite#

The test used a small project with a working application HTML file, a JavaScript entry importing React, and generated documentation containing a deliberately malformed inline module. The documentation directory was listed in the local Git ignore file. There was no custom Vite config for the initial run.

The application entry remained valid throughout the first before-and-after comparison:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Dependency scan fixture</title>
  </head>
  <body>
    <script type="module" src="/main.js"></script>
  </body>
</html>

Its JavaScript dependency was intentionally minimal:

import React from 'react'
 
console.log(React.version)

The failure was reproduced natively on Windows with Node 26.7.0, Vite 8.3.5 and React 19.2.4. The scan listed both application and documentation HTML, then identified a parse error inside the documentation's inline module. The fixture used Vite's development server and inspected its scan diagnostics; it did not test browser rendering or run inside Docker.

One surprising observation is useful when checking a repair: the development server still returned the application's HTML successfully while its dependency scan failed. The server's startup banner or a successful HTTP response therefore did not prove that dependency discovery had succeeded.

Fix: explicitly list the application HTML entries#

For an ordinary single-page application whose only intended HTML entry is the root HTML file, add this complete configuration:

import { defineConfig } from 'vite'
 
export default defineConfig({
  optimizeDeps: {
    entries: ['index.html'],
  },
})

The paths are patterns relative to the Vite project root. According to the entries option documentation, setting them replaces default entry inference. It does not delete the documentation files, repair their code, or change which files Git tracks. It changes where this dependency scan starts.

For a multipage application, list every intended application entry instead of copying the single-page example unchanged. If a second HTML file is a real page, excluding it merely because it contains an error is not a repair. Keep that page in the entry set and fix the file or import named by its child diagnostic. The boundary should follow the app's intended pages, not whichever list happens to suppress warnings.

Keep existing plugins and other settings in a real project's config. The minimal fixture has none, so its entire change is the entry list. Restart the development server after editing the configuration, and compare the diagnostic rather than making several unrelated dependency upgrades at once.

Verify that real application errors still fail#

The reproduction changed only the entry list for the first successful run. A second test then introduced the same kind of syntax defect into the real JavaScript entry while keeping that list. Scanning failed again, as it should. Correcting the application syntax restored a successful scan.

The recorded control results were:

CASE default: HTTP 200; scanFailure=true
CASE only-index: HTTP 200; scanFailure=false
CASE broken-app-still-fails: HTTP 200; scanFailure=true
CASE corrected-app: HTTP 200; scanFailure=false

This proves a limited result: restricting discovery can remove an unrelated generated-documentation failure without exempting the application's dependency graph from parsing. It does not prove that the generated documentation is valid, or that a production build will pass. Check the development log, load each intended app page, and run the project's normal production build separately.

If the build instead reports that it cannot resolve the HTML entry itself, inspect the project root and copied files. The missing HTML entry in Docker diagnosis covers an HTML file excluded from the build context. A scan configuration cannot restore a file that the container never received.

When the child error names esbuild instead#

For the original question's service-shutdown message, this entry-list reproduction is not a confirmed fix. Preserve the full preceding output and the installed package versions before reinstalling anything. The entry heading only says which operation was attempting work when the lower-level error surfaced.

A concrete platform-package error is more specific. If the log says the required esbuild platform package is missing inside a container, follow the Vite esbuild platform-installation diagnosis. That page distinguishes host dependencies mounted into a container from dependencies installed for the container's own platform. Do not infer that condition merely from a terminated service.

Likewise, a config-loading parse error mentioning a define key is a different branch. The Expected identifier but found import diagnosis concerns a verified esbuild regression while bundling Vite configuration. It should not be treated as a universal upgrade prescription for dependency scanning. Choose the next step from the actual diagnostic below the wrapper, and use an explicit entry list only when the unwanted HTML has been identified as the source of that failure.