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

Inspect `AggregateError.errors` for the exact oxc diagnostic (line/column and message).

vitejs/vite · error · AggregateError

oxc transform error

Error message

oxc transform error

What it means

Thrown by `replaceDefine` in the define plugin when oxc's `transformSync` reports errors while substituting `define` values into JS. oxc performs the actual text replacement/parse; if the input code or a `define` substitution produces invalid JS, oxc emits diagnostics wrapped in an `AggregateError`.

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 89620f09af)

Solutions

Inspect `AggregateError.errors` for the exact oxc diagnostic (line/column and message).
Ensure every `define` value is valid JS — wrap strings in quotes (`JSON.stringify`) and objects as literals.
Use Vite's `loadEnv` + `JSON.stringify(process.env.X)` pattern for env-based defines rather than raw string injection.
Fix the underlying syntax error in the source file if the define itself is fine.

Example fix

// before
export default defineConfig({
  define: { 'import.meta.env.CFG': '{ debug: true }' }, // invalid bare object
});
// after
export default defineConfig({
  define: { 'import.meta.env.CFG': JSON.stringify({ debug: true }) },
});

Defensive patterns

Strategy: validation

Validate before calling

function validateDefine(define) {
  for (const [k, v] of Object.entries(define)) {
    // values must be valid JS expressions; strings must be quoted
    if (typeof v === 'string' && v.length && !/^["'`].*["'`]$/.test(v) && /[^-+\w.,\s\[\]{}():?!<>=&|/*%]/.test(v)) {
      throw new Error(`define['${k}'] value may be invalid JS: ${v}. Use JSON.stringify for strings/objects.`);
    }
  }
}
// validateDefine(config.define);

Try / catch

try {
  await build();
} catch (e) {
  if (e instanceof AggregateError && e.message === 'oxc transform error') {
    for (const inner of e.errors) console.error(inner);
    console.error('Check config.define values are valid JS literals');
  }
  throw e;
}

Prevention

Always wrap env string/object define values with `JSON.stringify(...)`.
Avoid define keys that collide with real syntax tokens.
Typecheck source files so unparseable modules surface before the define transform.

When it happens

Trigger: `transformSync(id, code, { lang: 'js', sourceType: 'module', define, ... })` returns a non-empty `errors` array — e.g. a `define` value that, when substituted, breaks syntax, or source code that is unparseable as a module.

Common situations: A `define` entry whose replacement value contains invalid JS (e.g. unbalanced quotes, a raw JSON object not wrapped properly), define keys that overlap with syntax, or source files with syntax incompatible with `sourceType: 'module'`.

Related errors

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