mdx-js/mdx · warning

Unexpected deprecated option `jsxRuntime: 'classic'`, `pragm

Error message

Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate

What it means

This is not a thrown error but a deprecation warning emitted once by createProcessor (the core of `compile`/`compileSync`) when legacy v1/v2 options — `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource` — are passed to the MDX v3 core. In v3 the classic pragma configuration was replaced by ESM import/source configuration, so these options are ignored and the user is pointed to the migration guide.

Source

Thrown at packages/mdx/lib/core.js:192

  }

  // @ts-expect-error: throw an error for a runtime value which is not allowed
  // by the types.
  if (settings.format === 'detect') {
    unreachable(
      "Unexpected `format: 'detect'`, which is not supported by `createProcessor`, expected `'mdx'` or `'md'`"
    )
  }

  if (
    (settings.jsxRuntime === 'classic' ||
      settings.pragma ||
      settings.pragmaFrag ||
      settings.pragmaImportSource) &&
    !warned
  ) {
    warned = true
    console.warn(
      "Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate"
    )
  }

  const pipeline = unified().use(remarkParse)

  if (settings.format !== 'md') {
    pipeline.use(remarkMdx)
  }

  const remarkRehypeOptions = settings.remarkRehypeOptions || {}

  pipeline
    .use(remarkMarkAndUnravel)
    .use(settings.remarkPlugins || [])
    .use(remarkRehype, {
      ...remarkRehypeOptions,
      allowDangerousHtml: true,

View on GitHub (pinned to 685627a819)

Solutions

1. Remove `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, and `pragmaImportSource` from your options and follow https://mdxjs.com/migrating/v3/.
2. If you need automatic-runtime customization, use `jsxImportSource` (e.g. `jsxImportSource: 'preact'`) instead of pragma options.
3. If you truly need the classic runtime, configure it via the underlying `@mdx-js/mdx` recma plugins per the v3 migration guide, or stay on the older major version.

Example fix

// before
await compile(file, { jsxRuntime: 'classic', pragma: 'h', pragmaImportSource: 'preact' })
// after
await compile(file, { jsxImportSource: 'preact' })

const legacyKeys = ['jsxRuntime', 'pragma', 'pragmaFrag', 'pragmaImportSource']
const found = legacyKeys.filter((k) => k in (mdxOptions || {}))
if (found.length) console.warn('Deprecated MDX options detected, migrate per v3 guide:', found)

function usesLegacyMdxOptions(o) {
  return typeof o === 'object' && o !== null &&
    ['jsxRuntime', 'pragma', 'pragmaFrag', 'pragmaImportSource'].some((k) => k in o)
}

When it happens

Trigger: Calling `compile`/`compileSync`/processor with `jsxRuntime: 'classic'` or any of `pragma`, `pragmaFrag`, `pragmaImportSource` in the options (typically a carried-over v2 config).

Common situations: Upgrading mdx-js from v2 to v3 without updating config; tutorials or blog posts referencing the old classic-runtime API; monorepos where one package still sets pragma options shared with the MDX pipeline.

Related errors

• Missing `pragma` in classic runtime with `pragmaImportSource
• Expected `Fragment` given to `evaluate`
• Expected `jsxDEV` given to `evaluate`
• Expected `jsx` given to `evaluate`
• Expected `jsxs` given to `evaluate`

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