withastro/astro · error · Error

The markdown processor "${processor.name}" does not provide

Error message

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

What it means

The MDX Vite plugin checks the configured markdown `processor` for a `createMdxRenderer` method. Astro's default processor implements it; custom processors (e.g. a custom remark/rehype pipeline passed as `markdown` config, or a Starlight-typography-style processor) may not. If absent, the plugin throws a plain `Error` instructing the user to implement `createMdxRenderer`.

Source

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

					},
				});
				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 d081033d5f)

Solutions

1. If you pass a custom processor, add a `createMdxRenderer` method that returns an object with a `render(body, opts)` function returning `{ code, map, astroMetadata }`.
2. Remove the custom processor override and let Astro's built-in processor handle MDX.
3. Align `astro` and `@astrojs/mdx` to compatible versions (check the integration's peerDeps).

Example fix

// before — custom processor missing the MDX contract
export const processor = { name: 'mine', render: async () => ({ code: '' }) };

// after
export const processor = {
  name: 'mine',
  async render() { /* ... */ return { code, map, astroMetadata }; },
  createMdxRenderer() {
    return { render(body) { /* produce code/map/astroMetadata */ } };
  },
};

function processorSupportsMdx(processor: any): boolean {
  return typeof processor?.createMdxRenderer === 'function';
}
if (!processorSupportsMdx(config.markdown?.processor)) {
  throw new Error('Custom processor lacks createMdxRenderer — MDX will fail');
}

function hasMdxRenderer(p: unknown): p is { createMdxRenderer: () => { render: Function } } {
  return !!p && typeof (p as any)?.createMdxRenderer === 'function';
}

When it happens

Trigger: Setting `astro.config` `markdown` to a custom processor object (via `markdown.shikiApplyStyle` alternatives, custom processor injection, or an integration that swaps the processor) that lacks `createMdxRenderer`. Using `@astrojs/starlight` or another integration that customizes markdown in a way incompatible with MDX. Mismatched `@astrojs/mdx` and Astro core versions.

Common situations: Custom markdown processor integrations. Version skew between `astro` and `@astrojs/mdx`. Forking the markdown pipeline without re-implementing the MDX renderer contract.

Related errors

• `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `mar
• Unexpected problem adding heading IDs to Markdoc file. Did y
• NoMatchingImport
• [MDX] A remark or rehype plugin attempted to inject invalid
• Expected a matching import for component `${tagName}`. Did y

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