withastro/astro · error · Error

The markdown processor

Error message

The markdown processor "${processor.name}" does not provide MDX support. Implement `createMdxRenderer` on the processor to enable MDX rendering.

What it means

@astrojs/mdx does not compile MDX itself: it asks the active markdown processor for an MDX renderer via its createMdxRenderer method (vite-plugin-mdx iterates the configured processors). If the processor that handles markdown does not implement createMdxRenderer, there is no way to render .mdx files, so the Vite plugin throws this error at build/dev time.

Solutions

1. Implement createMdxRenderer on the custom processor; it must return a renderer whose render() resolves { code, map, astroMetadata }
2. Update the processor package to a version that provides createMdxRenderer
3. Remove the custom markdown processor so the default processor (which supports MDX) is used
4. If MDX support is not needed, remove @astrojs/mdx from the integration list

Example fix

// before
const processor = { name: 'my-processor', createRenderer() { /* markdown only */ } };
// after
const processor = {
  name: 'my-processor',
  createRenderer() { /* markdown path */ },
  createMdxRenderer(processor) {
    return {
      async render(source, opts) {
        const compiled = await compileMdx(source, opts);
        return { code: String(compiled.value), map: compiled.map ? JSON.stringify(compiled.map) : null, astroMetadata };
      },
    };
  },
};

// In astro.config before adding @astrojs/mdx:
function supportsMdx(p: any): boolean {
  return typeof p?.createMdxRenderer === 'function';
}
if (!supportsMdx(resolvedProcessor)) {
  throw new Error(`processor ${resolvedProcessor.name} cannot render MDX; skipping @astrojs/mdx`);
}

function supportsMdx(p: unknown): p is { createMdxRenderer: (processor: unknown) => unknown } {
  return typeof (p as any)?.createMdxRenderer === 'function';
}

try {
  await import('@astrojs/mdx').then((m) => m.default());
} catch (err) {
  if (String(err?.message).includes('does not provide MDX support')) {
    // fall back to running without MDX files
  } else throw err;
}

When it happens

Trigger: astro.config sets a custom markdown processor (e.g. a Markdoc-style or internal processor) that only implements createRenderer; a third-party processor package built against an older processor API; version drift where @astrojs/mdx expects createMdxRenderer but the processor package predates it.

Common situations: Combining @astrojs/mdx with a custom or experimental markdown processor; integrations that swap the processor under the hood; upgrading @astrojs/mdx ahead of the processor package.

Related errors

• not applied.
• not applied.
• on `mdx( )` deprecated. Pass to `unified( )` from…
• To inherit Markdown plugins in MDX, please use explicit…
• Apps must be an object with an id, a name and an entrypoint.

AI-assisted analysis of withastro/astro@3578d45d34 (2026-08-18). Data as JSON: /api/errors/65ef8dcd0f483b5b. Report an issue: GitHub.

Appendix: source

Thrown at packages/integrations/mdx/src/vite-plugin-mdx.ts:158

					},
				});
				const compiled = await unifiedProcessor.process(vfile);
				const astroMetadata = getAstroMetadata(vfile);
				if (!astroMetadata) {
					throw new Error(
						'Internal MDX error: Astro metadata is not set by rehype-analyze-astro-metadata',
					);
				}
				return {
					code: String(compiled.value),
					map: compiled.map ? JSON.stringify(compiled.map) : null,
					astroMetadata,
				};
			},
		};
	}

	throw new Error(
		`The markdown processor "${processor.name}" does not provide MDX support. ` +
			`Implement \`createMdxRenderer\` on the processor to enable MDX rendering.`,
	);
}

View on GitHub (pinned to 3578d45d34)