{"record":{"id":"f1f4f0142d43191d","repo":"withastro/astro","slug":"uncaught-error-partial-tag-requires-a-file-att","errorCode":null,"errorMessage":"(Uncaught error) Partial tag requires a 'file' attribute","messagePattern":"\\(Uncaught error\\) Partial tag requires a 'file' attribute","errorType":"exception","errorClass":"MarkdocError","httpStatus":null,"severity":"error","filePath":"packages/integrations/markdoc/src/content-entry-type.ts","lineNumber":177,"sourceCode":"\tmarkdocConfig,\n\tpluginContext,\n\traisePartialValidationErrors,\n}: {\n\tast: Node;\n\tfileUrl: URL;\n\troot: URL;\n\ttokenizer: any;\n\tallowHTML?: boolean;\n\tmarkdocConfig: MarkdocConfig;\n\tpluginContext: Rolldown.PluginContext;\n\traisePartialValidationErrors: (ast: Node, filePath: string) => void;\n}) {\n\tconst relativePartialPath = path.relative(fileURLToPath(root), fileURLToPath(fileUrl));\n\tfor (const node of ast.walk()) {\n\t\tif (node.type === 'tag' && node.tag === 'partial') {\n\t\t\tconst { file } = node.attributes;\n\t\t\tif (!file) {\n\t\t\t\tthrow new MarkdocError({\n\t\t\t\t\t// Should be caught by Markdoc validation step.\n\t\t\t\t\tmessage: `(Uncaught error) Partial tag requires a 'file' attribute`,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (markdocConfig.partials?.[file]) continue;\n\n\t\t\tlet partialPath: string;\n\t\t\tlet partialContents: string;\n\t\t\ttry {\n\t\t\t\tconst resolved = await pluginContext.resolve(file, fileURLToPath(fileUrl));\n\t\t\t\tlet partialId = resolved?.id;\n\t\t\t\tif (!partialId) {\n\t\t\t\t\tconst attemptResolveAsRelative = await pluginContext.resolve(\n\t\t\t\t\t\t'./' + file,\n\t\t\t\t\t\tfileURLToPath(fileUrl),\n\t\t\t\t\t);\n\t\t\t\t\tif (!attemptResolveAsRelative?.id) throw new Error();","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/markdoc/src/content-entry-type.ts#L159-L195","documentation":"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).","triggerScenarios":"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`.","commonSituations":"Author forgets the `file=` attribute when embedding a partial. Markdoc schema customization that overrides the partial tag definition. Migrating partial syntax between Markdoc versions.","solutions":["Add the required `file` attribute: `{% partial file=\"./header.mdoc\" / %}`.","If validation should have caught this, check your `markdocConfig` to ensure the built-in `partial` tag schema with `file: { required: true }` is not overridden.","Run Markdoc validation explicitly before build to surface the error at authoring time.","Verify the partial file path resolves relative to the `.mdoc` source."],"exampleFix":"{% partial file=\"./_nav.mdoc\" / %}","handlingStrategy":"validation","validationCode":"function assertPartialTag(node: { type: string; tag: string; attributes: Record<string, unknown> }) {\n  if (node.type === 'tag' && node.tag === 'partial' && !node.attributes.file) {\n    throw new Error('Partial tag requires a file attribute');\n  }\n}","typeGuard":"function isPartialWithFile(node: any): boolean {\n  return node?.type === 'tag' && node?.tag === 'partial' && typeof node?.attributes?.file === 'string' && node.attributes.file.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Always pair `{% partial %}` with `file=\"...\"`.","Add a Markdoc validation step in pre-commit to catch missing attributes.","Keep the built-in `partial` tag schema intact in `markdocConfig`."],"tags":["markdoc","content-collections","validation","authoring"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}