withastro/astro · error · MarkdocError

${rootRelativePath} contains invalid content: ${validati

Error message

**${rootRelativePath}** contains invalid content:
${validationErrors}

What it means

After Markdoc validates a content entry, the integration collects non-ignored validation errors (it skips `variable-undefined` and missing-partial `attribute-value-invalid` errors). If any remain, it throws a `MarkdocError` listing all of them, anchored to the first error's line and the Vite id so the overlay can display it.

Source

Thrown at packages/integrations/markdoc/src/content-entry-type.ts:260

	astroConfig: AstroConfig;
	filePath: string;
}) {
	const validationErrors = Markdoc.validate(ast, markdocConfig).filter((e) => {
		return (
			(e.error.level === 'error' || e.error.level === 'critical') &&
			// Ignore `variable-undefined` errors.
			// Variables can be configured at runtime,
			// so we cannot validate them at build time.
			e.error.id !== 'variable-undefined' &&
			// Ignore missing partial errors.
			// We will resolve these in `resolvePartials`.
			!(e.error.id === 'attribute-value-invalid' && /^Partial .+ not found/.test(e.error.message))
		);
	});

	if (validationErrors.length) {
		const rootRelativePath = path.relative(fileURLToPath(astroConfig.root), filePath);
		throw new MarkdocError({
			message: [
				`**${String(rootRelativePath)}** contains invalid content:`,
				...validationErrors.map((e) => `- ${e.error.message}`),
			].join('\n'),
			location: {
				// Error overlay does not support multi-line or ranges.
				// Just point to the first line.
				line: validationErrors[0].lines[0],
				file: viteId,
			},
		});
	}
}

function getUsedTags(markdocAst: Node) {
	const tags = new Set<string>();
	const validationErrors = Markdoc.validate(markdocAst);
	// Hack: run the validator with an empty config and look for 'tag-undefined'.

View on GitHub (pinned to d081033d5f)

Solutions

Read the listed error messages; each line corresponds to one Markdoc validation error with its line number.
Open the file at the reported line and fix the offending tag/attribute usage.
If a reported attribute is intentional, adjust your Markdoc schema (`markdocConfig.tags`/`nodes`) to allow it.
Re-run the build to confirm no further validation errors.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  Markdoc.validate(ast, markdocConfig);
} catch (e) {
  // surface per-error messages to the author
  throw e;
}

Prevention

Run `Markdoc.validate` during authoring/CI to catch schema violations early.
Keep `markdocConfig.tags`/`nodes` in sync with content usage.
Treat the first reported line as the anchor and fix downward.

When it happens

Trigger: Authoring `.mdoc` content that fails Markdoc validation: invalid tag usage, unknown attributes, type mismatches (e.g. a Number attribute given a string), custom schema violations. Any validation error except `variable-undefined` and the `Partial ... not found` attribute-value-invalid case.

Common situations: Using a custom Markdoc tag/attribute incorrectly. Forgetting required attributes on a custom node. Markdoc config schema change not reflected in content. Typo in a tag name.

Related errors

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

**${rootRelativePath}** contains invalid content: ${validati