withastro/astro · error · MarkdocError

(Uncaught error) Partial tag requires a 'file' attribute

Error message

(Uncaught error) Partial tag requires a 'file' attribute

What it means

The Markdoc integration walks the parsed AST looking for `{% partial %}` tags. If a `partial` tag is encountered without a `file` attribute, it throws `MarkdocError`. This path is meant to be caught earlier by Markdoc's own validation, so seeing it means the tag slipped past validation (e.g. validation disabled, partials config bypassed, or a custom schema).

Source

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

	markdocConfig,
	pluginContext,
	raisePartialValidationErrors,
}: {
	ast: Node;
	fileUrl: URL;
	root: URL;
	tokenizer: any;
	allowHTML?: boolean;
	markdocConfig: MarkdocConfig;
	pluginContext: Rolldown.PluginContext;
	raisePartialValidationErrors: (ast: Node, filePath: string) => void;
}) {
	const relativePartialPath = path.relative(fileURLToPath(root), fileURLToPath(fileUrl));
	for (const node of ast.walk()) {
		if (node.type === 'tag' && node.tag === 'partial') {
			const { file } = node.attributes;
			if (!file) {
				throw new MarkdocError({
					// Should be caught by Markdoc validation step.
					message: `(Uncaught error) Partial tag requires a 'file' attribute`,
				});
			}

			if (markdocConfig.partials?.[file]) continue;

			let partialPath: string;
			let partialContents: string;
			try {
				const resolved = await pluginContext.resolve(file, fileURLToPath(fileUrl));
				let partialId = resolved?.id;
				if (!partialId) {
					const attemptResolveAsRelative = await pluginContext.resolve(
						'./' + file,
						fileURLToPath(fileUrl),
					);
					if (!attemptResolveAsRelative?.id) throw new Error();

View on GitHub (pinned to d081033d5f)

Solutions

1. Add the required `file` attribute: `{% partial file="./header.mdoc" / %}`.
2. If validation should have caught this, check your `markdocConfig` to ensure the built-in `partial` tag schema with `file: { required: true }` is not overridden.
3. Run Markdoc validation explicitly before build to surface the error at authoring time.
4. Verify the partial file path resolves relative to the `.mdoc` source.

Example fix

{% partial file="./_nav.mdoc" / %}

function assertPartialTag(node: { type: string; tag: string; attributes: Record<string, unknown> }) {
  if (node.type === 'tag' && node.tag === 'partial' && !node.attributes.file) {
    throw new Error('Partial tag requires a file attribute');
  }
}

function isPartialWithFile(node: any): boolean {
  return node?.type === 'tag' && node?.tag === 'partial' && typeof node?.attributes?.file === 'string' && node.attributes.file.length > 0;
}

When it happens

Trigger: Authoring `{% partial / %}` or `{% partial %}...{% /partial %}` with no `file=` in a `.mdoc` file. Using a custom Markdoc config that defines a `partial` tag without the `file` required attribute, bypassing built-in validation. Validation step skipped or partials not registered in `markdocConfig.partials`.

Common situations: Author forgets the `file=` attribute when embedding a partial. Markdoc schema customization that overrides the partial tag definition. Migrating partial syntax between Markdoc versions.

Related errors

• **${rootRelativePath}** contains invalid content: ${validati
• ContentLoaderReturnsInvalidId
• ContentLoaderInvalidDataError
• ID must be a non-empty string
• File path must be relative to the site root. Got: ${filePath

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