What causes "Expected `jsxs` given to `evaluate`" in mdx-js/mdx?

Add `jsxs` from 'react/jsx-runtime' (or equivalent) to the evaluate options.

mdx-js/mdx · error · Error

Expected `jsxs` given to `evaluate`

Error message

Expected `jsxs` given to `evaluate`

What it means

In production mode the compiled MDX code calls `jsxs` for elements with multiple children (static children optimization). resolveEvaluateOptions therefore requires `jsxs` whenever `development` is falsy, and throws this error if it is absent, because the generated program would otherwise crash at runtime.

Source

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

 */
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

Add `jsxs` from 'react/jsx-runtime' (or equivalent) to the evaluate options.
Import the full set `Fragment, jsx, jsxs` as one unit to avoid partial runtimes.
If you intended development mode, set `development: true` and pass `jsxDEV` instead.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (!development && !runtime.jsxs) {
  throw new Error('evaluate options require `jsxs` when development is falsy')
}

Type guard

function hasJsxs(rt) {
  return typeof rt === 'object' && rt !== null && typeof rt.jsxs === 'function'
}

Try / catch

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

Prevention

Import the full `{ Fragment, jsx, jsxs }` set as one statement so bundlers/tree-shaking can't drop parts.
Map non-React libraries' multi-child factories to `jsxs` explicitly in your adapter.
Smoke-test evaluation of MDX containing multi-element JSX in CI.

When it happens

Trigger: Calling `evaluate(code, { Fragment, jsx })` without `jsxs`; passing a minimal runtime object missing the `jsxs` export; Vue/Solid adapters where the multi-child factory has a different name and wasn't mapped to `jsxs`.

Common situations: Hand-assembled evaluate options; bundler tree-shaking removing `jsxs`; copying dev-mode config (`jsxDEV` only) into a production path.

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

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