{"record":{"id":"f673b29b11e3397e","repo":"mdx-js/mdx","slug":"missing-pragma-in-classic-runtime-with-pragmaim","errorCode":null,"errorMessage":"Missing `pragma` in classic runtime with `pragmaImportSource`","messagePattern":"Missing `pragma` in classic runtime with `pragmaImportSource`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mdx/lib/plugin/recma-document.js","lineNumber":102,"sourceCode":"    if (jsxRuntime === 'classic' && pragmaFrag) {\n      injectPragma(tree, '@jsxFrag', pragmaFrag)\n    }\n\n    if (jsxRuntime === 'classic' && pragma) {\n      injectPragma(tree, '@jsx', pragma)\n    }\n\n    if (jsxRuntime === 'automatic' && jsxImportSource) {\n      injectPragma(tree, '@jsxImportSource', jsxImportSource)\n    }\n\n    if (jsxRuntime) {\n      injectPragma(tree, '@jsxRuntime', jsxRuntime)\n    }\n\n    if (jsxRuntime === 'classic' && pragmaImportSource) {\n      if (!pragma) {\n        throw new Error(\n          'Missing `pragma` in classic runtime with `pragmaImportSource`'\n        )\n      }\n\n      handleEsm({\n        type: 'ImportDeclaration',\n        specifiers: [\n          {\n            type: 'ImportDefaultSpecifier',\n            local: {type: 'Identifier', name: pragma.split('.')[0]}\n          }\n        ],\n        attributes: [],\n        source: {type: 'Literal', value: pragmaImportSource}\n      })\n    }\n\n    // Find the `export default`, the JSX expression, and leave the rest","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/mdx-js/mdx/blob/685627a819567c0788eadb85f5f57065bcc81c2c/packages/mdx/lib/plugin/recma-document.js#L84-L120","documentation":"recma-document throws this when the MDX pipeline is configured with `jsxRuntime: 'classic'` together with `pragmaImportSource` but no `pragma` option. In classic JSX runtime the compiler must know the exact identifier to import the JSX factory from (via `pragma`); `pragmaImportSource` only names the module, so without `pragma` it cannot emit a valid import. The library refuses to generate broken code and fails fast.","triggerScenarios":"Calling `compile`/`createProcessor` from `mdx` with `recmaPlugins`/options where `jsxRuntime: 'classic'` and `pragmaImportSource` are set but `pragma` is undefined (e.g. only `pragmaImportSource: 'preact/compat'` given, or `pragma` typo'd/removed).","commonSituations":"Migrating from MDX v1/v2 to v3 where classic-runtime options were partially carried over; switching to Preact/other JSX libraries and setting `pragmaImportSource` while forgetting `pragma: 'h'`; copying a config snippet that lists `pragmaImportSource` but omits `pragma`.","solutions":["Add the `pragma` option alongside `pragmaImportSource`, e.g. `pragma: 'h'` for Preact (`pragmaImportSource: 'preact'`).","If you do not need the classic runtime, remove `jsxRuntime: 'classic'` and `pragmaImportSource` and use the default automatic runtime.","If migrating to MDX v3, drop classic-runtime options entirely and configure the JSX runtime via `jsxImportSource` / `development` as described in https://mdxjs.com/migrating/v3/."],"exampleFix":"// before\nawait compile(file, { jsxRuntime: 'classic', pragmaImportSource: 'preact' })\n// after\nawait compile(file, { jsxRuntime: 'classic', pragma: 'h', pragmaFrag: 'Fragment', pragmaImportSource: 'preact' })","handlingStrategy":"validation","validationCode":"const opts = mdxOptions\nif (opts?.jsxRuntime === 'classic' && opts.pragmaImportSource && !opts.pragma) {\n  throw new Error(\"pragmaImportSource requires a matching pragma when jsxRuntime is 'classic'\")\n}","typeGuard":"function hasClassicPragmaPair(o) {\n  return typeof o === 'object' && o !== null &&\n    (o.jsxRuntime !== 'classic' || !o.pragmaImportSource || typeof o.pragma === 'string')\n}","tryCatchPattern":"try {\n  await compile(file, mdxOptions)\n} catch (err) {\n  if (err.message.includes('Missing `pragma` in classic runtime')) {\n    console.error('Add `pragma` when using classic JSX runtime with pragmaImportSource')\n  } else throw err\n}","preventionTips":["Always set `pragma`, `pragmaFrag`, and `pragmaImportSource` together when using `jsxRuntime: 'classic'`.","Centralize MDX options in one config module so the classic-runtime triplet is never partially applied.","Prefer the default automatic runtime unless a specific JSX library requires classic.","Run a compile smoke test in CI over a sample MDX file to surface config errors early."],"tags":["mdx","configuration","jsx-runtime"],"backgroundTag":"missing-required-option","analyzedSha":"685627a819567c0788eadb85f5f57065bcc81c2c","analyzedAt":"2026-09-02T16:11:18.599Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}