What causes "oxc transform error" in vitejs/vite?

Read the individual errors inside the AggregateError (e.cause or iterate err.errors) to get the precise oxc message and code span.

vitejs/vite · error · AggregateError

oxc transform error

Error message

oxc transform error

What it means

replaceDefine runs oxc's transformSync to substitute global identifiers defined via the 'define' option (and import.meta.env.* replacements). If oxc reports any transform errors (syntax errors, invalid define substitution, unparseable input), Vite wraps them in an AggregateError labelled 'oxc transform error'. Each entry in result.errors describes one underlying oxc diagnostic.

Solutions

Read the individual errors inside the AggregateError (e.cause or iterate err.errors) to get the precise oxc message and code span.
Correct the offending source code or the define entry that caused the bad substitution.
If the syntax is valid TS/JSX that oxc rejects, verify the file is being parsed with the right lang (oxc infers from extension; rename or configure accordingly).
As a last resort, simplify or remove the suspect define key to confirm it is the trigger, then re-add with a valid value.

Example fix

// before
define: { 'process.env.NODE_ENV': undefined }
// after
define: { 'process.env.NODE_ENV': JSON.stringify('development') }

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate define keys/values before building
function validateDefine(define) {
  for (const [k, v] of Object.entries(define)) {
    if (typeof k !== 'string' || k.trim() === '') throw new Error(`Invalid define key: ${k}`)
    if (v === undefined) throw new Error(`define['${k}'] is undefined; use JSON.stringify or a literal`)
  }
}
validateDefine(config.define)

Type guard

function isSafeDefineValue(v): boolean {
  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null
}

Try / catch

try {
  return replaceDefine(environment, code, id, define)
} catch (e) {
  const errs = (e.errors ?? (e.cause?.errors) ?? [e])
  for (const err of errs) logger.error(`oxc: ${err.message}`)
  throw e
}

Prevention

Always JSON.stringify string env values in define rather than injecting raw.
Never set a define value to undefined.
Run a small transform test on a sample file when changing define config.

When it happens

Trigger: Configuring define with a key/value that produces invalid JavaScript after substitution, passing code with a syntax error to replaceDefine, or an oxc version regression that mishandles a specific construct. Surfaces during dev serve or build whenever a module containing a define-replaceable identifier is transformed.

Common situations: A define value like `process.env.X: undefined` emitted as a bare token, JSX/TS syntax oxc rejects (e.g. decorators without the right parser flag), or a malformed custom define key (e.g. containing spaces). Also occurs after upgrading Vite/rolldown/oxc where parser defaults changed.

Related errors

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/1d60a752eb687dd9. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/plugins/define.ts:191

  id: string,
  define: Record<string, string>,
): {
  code: string
  map: ReturnType<typeof transformSync>['map'] | null
} {
  const result = transformSync(id, code, {
    lang: 'js',
    sourceType: 'module',
    define,
    sourcemap:
      environment.config.command === 'build'
        ? !!environment.config.build.sourcemap
        : true,
    tsconfig: false,
  })

  if (result.errors.length > 0) {
    throw new AggregateError(result.errors, 'oxc transform error')
  }

  return {
    code: result.code,
    map: result.map || null,
  }
}

/**
 * Like `JSON.stringify` but keeps raw string values as a literal
 * in the generated code. For example: `"window"` would refer to
 * the global `window` object directly.
 */
export function serializeDefine(define: Record<string, any>): string {
  let res = `{`
  const keys = Object.keys(define).sort()
  for (let i = 0; i < keys.length; i++) {
    const key = keys[i]

View on GitHub (pinned to b4d66fee14)