vitejs/vite · error · Error

Option "build.lib.name" is required when output formats incl

Error message

Option "build.lib.name" is required when output formats include "umd" or "iife".

What it means

In resolveBuildOutputs (build.ts:1066), UMD and IIFE formats require a global variable name to attach the bundle to. If the formats include 'umd' or 'iife' (and outputs is not an array) but build.lib.name is unset, Vite throws.

Source

Thrown at packages/vite/src/node/build.ts:1067

  if (libOptions) {
    const libHasMultipleEntries =
      typeof libOptions.entry !== 'string' &&
      libOptions.entry &&
      Object.values(libOptions.entry).length > 1
    const libFormats =
      libOptions.formats ||
      (libHasMultipleEntries ? ['es', 'cjs'] : ['es', 'umd'])

    if (!Array.isArray(outputs)) {
      if (libFormats.includes('umd') || libFormats.includes('iife')) {
        if (libHasMultipleEntries) {
          throw new Error(
            'Multiple entry points are not supported when output formats include "umd" or "iife".',
          )
        }

        if (!libOptions.name) {
          throw new Error(
            'Option "build.lib.name" is required when output formats include "umd" or "iife".',
          )
        }
      }

      return libFormats.map((format) => ({ ...outputs, format }))
    }

    // By this point, we know "outputs" is an Array.
    if (libOptions.formats) {
      logger.warn(
        colors.yellow(
          '"build.lib.formats" will be ignored because "build.rolldownOptions.output" is already an array format.',
        ),
      )
    }

    outputs.forEach((output) => {

View on GitHub (pinned to 89620f09af)

Solutions

Set build.lib.name to the desired global variable name, e.g. name: 'MyLib'.
If you don't need a browser global, drop 'umd'/'iife' from formats and use 'es'/'cjs'.
Ensure the name is a valid JS identifier (no hyphens).

Example fix

// before
build: { lib: { entry: 'src/index.ts', formats: ['umd'] } }
// after
build: { lib: { entry: 'src/index.ts', name: 'MyLib', formats: ['umd'] } }

Defensive patterns

Strategy: validation

Validate before calling

const lib = config.build?.lib
const fmts = lib?.formats
if (lib && (fmts?.includes('umd') || fmts?.includes('iife')) && !lib.name) {
  throw new Error('build.lib.name is required for umd/iife formats')
}

Type guard

function hasUmdName(lib: any): boolean {
  const fmts = lib.formats
  return !(fmts?.includes('umd') || fmts?.includes('iife')) || Boolean(lib.name)
}

Prevention

Whenever you add 'umd'/'iife' to formats, set build.lib.name simultaneously.
Use a valid JS identifier (no hyphens) for the global name.
Consider es/cjs if you don't need a browser global.

When it happens

Trigger: Setting build.lib.formats to include 'umd'/'iife' (or defaulting into 'umd' for a single entry) without providing build.lib.name.

Common situations: Switching a library config to UMD/IIFE and forgetting the global name; relying on defaults which add 'umd' for single-entry libs.

Related errors

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/7ae0fe3771f0b493.json. Report an issue: GitHub.