vuejs/core · error · Error

[@vue/compiler-core] decodeEntities option is required in br

Error message

[@vue/compiler-core] decodeEntities option is required in browser builds.

What it means

Thrown by @vue/compiler-core's parser only in browser builds (__BROWSER__ true, not __TEST__) when the decodeEntities option is missing. In a browser there is no Node.js entity decoder, so the parser needs an explicit function to decode HTML entities (named, decimal, and hex). The guard at parser.ts:1050 deliberately hard-fails rather than silently producing malformed output. The inverse non-browser branch only warns if decodeEntities is passed pointlessly.

Source

Thrown at packages/compiler-core/src/parser.ts:1050

  if (options) {
    let key: keyof ParserOptions
    for (key in options) {
      if (options[key] != null) {
        // @ts-expect-error
        currentOptions[key] = options[key]
      }
    }
  }

  if (__DEV__) {
    if (!__BROWSER__ && currentOptions.decodeEntities) {
      console.warn(
        `[@vue/compiler-core] decodeEntities option is passed but will be ` +
          `ignored in non-browser builds.`,
      )
    } else if (__BROWSER__ && !__TEST__ && !currentOptions.decodeEntities) {
      throw new Error(
        `[@vue/compiler-core] decodeEntities option is required in browser builds.`,
      )
    }
  }

  tokenizer.mode =
    currentOptions.parseMode === 'html'
      ? ParseMode.HTML
      : currentOptions.parseMode === 'sfc'
        ? ParseMode.SFC
        : ParseMode.BASE

  tokenizer.inXML =
    currentOptions.ns === Namespaces.SVG ||
    currentOptions.ns === Namespaces.MATH_ML

  const delimiters = options && options.delimiters
  if (delimiters) {

View on GitHub (pinned to a2b40db9a8)

Solutions

1. Pass a decodeEntities function in the compiler options, e.g. decodeEntities from the he package or a shared parserDecodeOptions with @vue/shared's decodeHtml.
2. If you do not actually need browser compilation, import the Node/CJS build of @vue/compiler-core instead of the *-esm-browser entry so the guard's __BROWSER__ branch is not compiled in.
3. For library authors wrapping the compiler, reuse the decodeEntities option that @vue/compiler-sfc and @vue/compiler-dom already wire up rather than building your own.
4. During testing set __TEST__ (the vitest define) so the guard is skipped, only if you are intentionally testing parser internals.

Example fix

// before (browser build)
import { baseParse } from '@vue/compiler-core'
const ast = baseParse('<div>&amp;</div>')

// after
import { baseParse } from '@vue/compiler-core'
import { decodeHtml } from '@vue/shared'
const ast = baseParse('<div>&amp;</div>', {
  decodeEntities: (text, asAttr) => decodeHtml(text, asAttr),
})

// Before calling baseParse/compile in a browser build, ensure decodeEntities is set.
import { baseParse } from '@vue/compiler-core'
import { decodeHtml } from '@vue/shared'

function safeParse(source: string, opts: Record<string, unknown> = {}) {
  if (!opts.decodeEntities) {
    opts.decodeEntities = (text: string, asAttr: boolean) => decodeHtml(text, asAttr)
  }
  return baseParse(source, opts as any)
}

function hasDecodeEntities(opts: unknown): opts is { decodeEntities: (t: string, a?: boolean) => string } {
  return !!opts && typeof (opts as any).decodeEntities === 'function'
}

When it happens

Trigger: Calling parse()/baseParse()/compile() from a browser-targeted build of @vue/compiler-core without supplying options.decodeEntities. Importing the browser ESM entry (e.g. @vue/compiler-core/dist/compiler-core.esm-browser.js) and compiling a template directly.

Common situations: Bundling a custom in-browser template compiler and forgetting the decodeEntities callback; upgrading compiler-core to a version that made the option mandatory; using the browser build where previously the Node build was pulled in by the bundler.

Related errors

• [@vue/compiler-sfc] `modules` option is not supported in the
• [@vue/compiler-sfc] Style preprocessing in the browser build
• [@vue/compiler-sfc] Template preprocessing in the browser bu
• [@vue/compiler-sfc] <script> and <script setup> must have th
• [@vue/compiler-sfc] SFC contains no <script> tags.

AI-assisted analysis of vuejs/core@a2b40db9a8 (2026-08-12). Data as JSON: /api/errors/9045ec7a1513c977. Report an issue: GitHub.