{"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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/markdoc/src/content-entry-type.ts#L159-L195","documentation":"The Markdoc integration walks a document's AST to resolve `{% partial %}` tags, which must carry a `file` attribute naming the partial to inline. A partial node without `file` has nothing to resolve, so the walker throws this MarkdocError (normally the earlier Markdoc validation pass catches it first — this is the safety net).","triggerScenarios":"Writing `{% partial /%}` (or `{% partial %}...{% /partial %}`) in a .mdoc/Markdoc content file without a `file` attribute.","commonSituations":"Typos like `filepath=` or missing quotes around the attribute; copy-pasting partial examples from docs of other template engines; partial wrappers intended to nest content but mistakenly using the reserved `partial` tag name.","solutions":["Add the required attribute: `{% partial file=\"headers/banner\" /%}`.","Check for typos in the attribute name (`file`, not `path`/`filepath`/`src`).","If you meant a custom container, rename your tag to something other than `partial` in the Markdoc config."],"exampleFix":"{% partial /%}\n\n{% partial file=\"partials/nav\" /%}","handlingStrategy":"validation","validationCode":"// Lint .mdoc sources before build: every {% partial %} must carry file=\"...\"\nimport { Markdoc } from '@markdoc/markdoc';\nimport { globSync } from 'glob';\nimport fs from 'node:fs';\nfor (const f of globSync('src/**/*.mdoc')) {\n  for (const node of Markdoc.parse(fs.readFileSync(f, 'utf8')).walk()) {\n    if (node.type === 'tag' && node.tag === 'partial' && !node.attributes.file) {\n      throw new Error(`${f}: {% partial %} missing required \"file\" attribute`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat `partial` as reserved: only use it with an explicit `file` attribute.","Provide partial snippets/autocompletion in editor tooling so the attribute is never omitted.","Run Markdoc validation in CI so authors learn of the mistake before build time."],"tags":["markdoc","partials","content","required-attribute"],"backgroundTag":"missing-required-attribute","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}