mdx-js/mdx · error · Error

Expected `Fragment` given to `evaluate`

Error message

Expected `Fragment` given to `evaluate`

What it means

resolveEvaluateOptions validates the runtime pieces passed to `evaluate`/`run`. `Fragment` is the component used for JSX fragments (`<>...</>`), and the compiled code references it directly, so it must be supplied. If it is missing, MDX cannot evaluate the generated program and throws immediately.

Source

Thrown at packages/mdx/lib/util/resolve-evaluate-options.js:70

 *
 * @param {Readonly<EvaluateOptions> | null | undefined} options
 *   Configuration.
 * @returns {{compiletime: CompileOptions, runtime: RunOptions}}
 *   Split options.
 */
export function resolveEvaluateOptions(options) {
  const {
    Fragment,
    baseUrl,
    development,
    jsx,
    jsxDEV,
    jsxs,
    useMDXComponents,
    ...rest
  } = options || {}

  if (!Fragment) throw new Error('Expected `Fragment` given to `evaluate`')
  if (development) {
    if (!jsxDEV) throw new Error('Expected `jsxDEV` given to `evaluate`')
  } else {
    if (!jsx) throw new Error('Expected `jsx` given to `evaluate`')
    if (!jsxs) throw new Error('Expected `jsxs` given to `evaluate`')
  }

  return {
    compiletime: {
      ...rest,
      development,
      outputFormat: 'function-body',
      providerImportSource: useMDXComponents ? '#' : undefined
    },
    runtime: {Fragment, baseUrl, jsx, jsxDEV, jsxs, useMDXComponents}
  }
}

View on GitHub (pinned to 685627a819)

Solutions

1. Pass `Fragment` from your JSX runtime: `evaluate(code, { ...runtime, Fragment })` with `Fragment` imported from 'react/jsx-runtime' (or the equivalent for your library).
2. If your library has no `Fragment` export (e.g. Preact's `Fragment` from 'preact'), import and alias it explicitly.
3. Use the runtime object exported by a `@mdx-js/*` jsx-runtime helper rather than hand-assembling options.

Example fix

// before
const result = await evaluate(code, { jsx, jsxs })
// after
import { Fragment, jsx, jsxs } from 'react/jsx-runtime'
const result = await evaluate(code, { Fragment, jsx, jsxs })

function assertRuntime(rt) {
  if (!rt || !rt.Fragment) throw new Error('evaluate options require `Fragment`')
}

function hasFragment(rt) {
  return typeof rt === 'object' && rt !== null && typeof rt.Fragment === 'function'
}

try {
  const result = await evaluate(code, runtime)
} catch (err) {
  if (err.message === 'Expected `Fragment` given to `evaluate`') {
    console.error('Provide Fragment from your jsx-runtime in evaluate options')
  } else throw err
}

When it happens

Trigger: Calling `evaluate()` (or `run`/`evaluate` via runtime) without `Fragment` in the options object, e.g. `evaluate(code, { jsx, jsxs })` where options come from a spread that omits `Fragment`.

Common situations: Hand-writing evaluate options instead of using a helper like `*jsx-runtime` exports; passing only `jsx`/`jsxs` from 'react/jsx-runtime' and forgetting `Fragment`; destructuring options and accidentally dropping `Fragment`; Vue/Solid/Preact setups where the fragment export has a different name and wasn't mapped.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Expected `jsx` given to `evaluate`
• Expected `jsxs` given to `evaluate`
• Missing `pragma` in classic runtime with `pragmaImportSource
• Expected `jsxDEV` given to `evaluate`
• Unexpected deprecated option `jsxRuntime: 'classic'`, `pragm

AI-assisted analysis of mdx-js/mdx@685627a819 (2026-09-02). Data as JSON: /api/errors/bc5b1b2d3cb867a7. Report an issue: GitHub.