vuejs/vue-cli · error · Error

Do not modify webpack output.publicPath directly. Use the "p

Error message

Do not modify webpack output.publicPath directly. Use the "publicPath" option in vue.config.js instead.

What it means

During a non-app build (e.g. library mode, where VUE_CLI_BUILD_TARGET is set to something other than 'app'), Service.verifyConfig compares webpack's `config.output.publicPath` against the configured `publicPath` option. If they differ, a plugin/hook mutated publicPath directly, which breaks library path resolution, so it is rejected.

Source

Thrown at packages/@vue/cli-service/lib/Service.js:308

    // #2206 If config is merged by merge-webpack, it discards the __ruleNames
    // information injected by webpack-chain. Restore the info so that
    // vue inspect works properly.
    if (config !== original) {
      cloneRuleNames(
        config.module && config.module.rules,
        original.module && original.module.rules
      )
    }

    // check if the user has manually mutated output.publicPath
    const target = process.env.VUE_CLI_BUILD_TARGET
    if (
      !process.env.VUE_CLI_TEST &&
      (target && target !== 'app') &&
      config.output.publicPath !== this.projectOptions.publicPath
    ) {
      throw new Error(
        `Do not modify webpack output.publicPath directly. ` +
        `Use the "publicPath" option in vue.config.js instead.`
      )
    }

    if (
      !process.env.VUE_CLI_ENTRY_FILES &&
      typeof config.entry !== 'function'
    ) {
      let entryFiles
      if (typeof config.entry === 'string') {
        entryFiles = [config.entry]
      } else if (Array.isArray(config.entry)) {
        entryFiles = config.entry
      } else {
        entryFiles = Object.values(config.entry || []).reduce((allEntries, curr) => {
          return allEntries.concat(curr)
        }, [])

View on GitHub (pinned to 7eb93c169c)

Solutions

1. Set `publicPath` in vue.config.js instead of mutating webpack output.
2. Remove the `config.output.publicPath = ...` line from your webpack hooks.

Example fix

// vue.config.js — before (in chainWebpack)
config.output.publicPath = '/assets/'
// after
module.exports = { publicPath: '/assets/' }

// inside your webpack hook — never mutate; assert equality instead
const expected = options.publicPath
if (config.output.publicPath !== expected) {
  throw new Error('Refusing to mutate output.publicPath; set the publicPath option instead')
}

When it happens

Trigger: In chainWebpack or configureWebpack, setting `config.output.publicPath = '...'` while building with a lib/wc target.

Common situations: Library builds with copy-pasted webpack snippets that override publicPath; plugins that assume app mode.

Related errors

• Configuration Error: Avoid modifying webpack output.public
• Configuration Error: Avoid modifying webpack output.path d
• Configuration Error: Do not set output directory to projec
• Cannot find polyfill ${item}, please refer to 'core-js-compa
• transpileDependencies only accepts an array of string or reg

AI-assisted analysis of vuejs/vue-cli@7eb93c169c (2026-08-13). Data as JSON: /api/errors/b0679b3371492b66. Report an issue: GitHub.