vuejs/vue · error · Error

Server-side bundle should have one single entry file. Avoid

Error message

Server-side bundle should have one single entry file. Avoid using CommonsChunkPlugin in the server config.

What it means

Thrown by VueSSRServerPlugin during webpack emit when the server bundle's entry point has more than one JS asset. SSR requires a single self-contained entry file because the bundle runner evaluates one entry module; multiple chunks (e.g. a common/vendor chunk split out by CommonsChunkPlugin or splitChunks) break the direct-mode runner. The plugin filters entryInfo.assets to JS files and checks the count.

Source

Thrown at packages/server-renderer/src/webpack-plugin/server.ts:31

  apply(compiler) {
    validate(compiler)

    const stage = 'PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER'
    onEmit(compiler, 'vue-server-plugin', stage, (compilation, cb) => {
      const stats = compilation.getStats().toJson()
      const entryName = Object.keys(stats.entrypoints)[0]
      const entryInfo = stats.entrypoints[entryName]

      if (!entryInfo) {
        // #5553
        return cb()
      }

      const entryAssets = entryInfo.assets.map(getAssetName).filter(isJS)

      if (entryAssets.length > 1) {
        throw new Error(
          `Server-side bundle should have one single entry file. ` +
            `Avoid using CommonsChunkPlugin in the server config.`
        )
      }

      const entry = entryAssets[0]
      if (!entry || typeof entry !== 'string') {
        throw new Error(
          `Entry "${entryName}" not found. Did you specify the correct entry option?`
        )
      }

      const bundle = {
        entry,
        files: {},
        maps: {}
      }

View on GitHub (pinned to 9e88707940)

Solutions

1. Disable code splitting for the server build: set optimization.splitChunks = false (webpack 5) or remove CommonsChunkPlugin (webpack 4).
2. Use a server-specific webpack config that does not split chunks: target: 'node', output.libraryTarget: 'commonjs2'.
3. Externalize node_modules (externals: nodeExternals()) instead of splitting them into chunks.
4. Verify after rebuild that the server bundle manifest lists a single entry file.

Example fix

// before — splitChunks inherited from client config
module.exports = {
  // ...
  optimization: { splitChunks: { chunks: 'all' } }
}

// after — disable splitting for SSR
module.exports = {
  target: 'node',
  output: { libraryTarget: 'commonjs2', filename: '[name].js' },
  optimization: { splitChunks: false },
  externals: require('webpack-node-externals')()
}

// Validate webpack server config before running the build.
function assertServerWebpackConfig(config: any): void {
  if (config.target !== 'node') console.warn('server config target should be node')
  if (config.optimization && config.optimization.splitChunks && config.optimization.splitChunks !== false) {
    throw new Error(
      'Server webpack config must disable optimization.splitChunks to avoid multiple entry assets.'
    )
  }
  const commons = (config.plugins || []).find((p: any) => p.constructor && p.constructor.name === 'CommonsChunkPlugin')
  if (commons) throw new Error('Remove CommonsChunkPlugin from the server webpack config.')
}

function serverConfigHasSingleEntry(config: any): boolean {
  return !config.optimization?.splitChunks || config.optimization.splitChunks === false
}

// The error throws during webpack emit (inside the plugin's onEmit hook).
// Wrap the webpack build callback:
compiler.run((err, stats) => {
  if (err && err.message.includes('should have one single entry file')) {
    console.error('Fix: set optimization.splitChunks = false in the server config')
  }
})

When it happens

Trigger: Webpack server config uses optimization.splitChunks, CommonsChunkPlugin, or any code-splitting that produces a vendor chunk alongside the entry chunk. The entry then has 2+ JS assets after filtering, triggering the guard.

Common situations: Reusing the client webpack config (which has splitChunks for caching) for the server build. Adding CommonsChunkPlugin without disabling it for the server target. Webpack 5 splitChunks default config inherited into server build.

Related errors

• Entry "${entryName}" not found. Did you specify the correct
• bundle export should be a function when using { runInNewCont
• \n\nVue packages version mismatch:\n\n- vue@${vueVersion}\n-
• Invalid JSON bundle file: ${bundle}
• Cannot locate bundle file: ${bundle}

AI-assisted analysis of vuejs/vue@9e88707940 (2026-08-11). Data as JSON: /api/errors/ff8f3cb6d019f882. Report an issue: GitHub.