{"record":{"id":"294fce7d89cee013","repo":"vectordotdev/vector","slug":"deprecation-fragment-must-begin-with-yaml-frontmatter","errorCode":null,"errorMessage":"Deprecation fragment {} must begin with YAML frontmatter (---)","messagePattern":"Deprecation fragment (.+?) must begin with YAML frontmatter \\(---\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vdev/src/utils/deprecation.rs","lineNumber":203,"sourceCode":"    }\n\n    Ok(DeprecationEntry {\n        filename,\n        what: fm.what.trim().to_string(),\n        deprecated_since: fm.deprecated_since,\n        description: body.trim().to_string(),\n    })\n}\n\n/// Split the raw file contents into the frontmatter string and the body.\n/// The file must begin with `---`, and have a closing `---` on its own line.\nfn split_frontmatter<'a>(content: &'a str, path: &Path) -> Result<(&'a str, &'a str)> {\n    let content = content.trim_start();\n    // Advance past the opening `---` (and optional trailing whitespace on that line)\n    let after_open = content\n        .strip_prefix(\"---\")\n        .ok_or_else(|| {\n            anyhow!(\n                \"Deprecation fragment {} must begin with YAML frontmatter (---)\",\n                path.display()\n            )\n        })?\n        .trim_start_matches([' ', '\\t'])\n        .trim_start_matches('\\n');\n\n    let (frontmatter, rest) = after_open.split_once(\"\\n---\").ok_or_else(|| {\n        anyhow!(\n            \"Deprecation fragment {} has unclosed frontmatter\",\n            path.display()\n        )\n    })?;\n    let rest = rest.trim_start_matches(['\\r', '\\n']);\n    let body = rest.trim_start_matches(['\\r', '\\n']);\n\n    Ok((frontmatter, body))\n}","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/vectordotdev/vector/blob/bdb87aeaa4c4ff27c0ba643c1c77b21bf2ef4013/vdev/src/utils/deprecation.rs#L185-L221","documentation":"Deprecation fragments are Markdown files that must start with a YAML frontmatter block delimited by an opening `---` line. `split_frontmatter` trims leading whitespace and requires the content to literally begin with `---`; if the prefix is missing it fails with this error naming the fragment path. The frontmatter carries the structured deprecation metadata the parser needs.","triggerScenarios":"parse_deprecation_fragment is called on a fragment file whose content (after trimming) does not start with `---` — e.g. the file starts directly with Markdown prose, an HTML comment, or a BOM/odd whitespace before the dashes.","commonSituations":"Adding a new deprecation fragment in `changelog.d`/docs and forgetting the frontmatter header; an editor or generator stripping the leading `---`; a UTF-8 BOM at the start of the file preventing the `---` prefix match.","solutions":["Open the fragment file in the error and add a YAML frontmatter block starting with `---` as the very first line.","Remove any BOM or stray characters (including HTML comments) before the opening `---`.","Compare against an existing valid deprecation fragment and match its header structure, then re-run the check."],"exampleFix":"# before\ndeprecates the `foo` transform.\n\n# after\n---\ndate: 2026-09-15\ncomponent: transform/foo\n---\ndeprecates the `foo` transform.","handlingStrategy":"validation","validationCode":"def has_frontmatter(text):\n    return text.lstrip('\\ufeff \\t\\n\\r').startswith('---')\n\ncontent = open(path, encoding='utf-8-sig').read()\nassert has_frontmatter(content), f\"{path} must start with YAML frontmatter\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Copy an existing valid deprecation fragment as a template when creating new ones.","Save files as UTF-8 without BOM so the leading `---` is matched.","Add a CI check that greps new fragments for an opening `---` on line 1."],"tags":["yaml","frontmatter","deprecation","rust"],"backgroundTag":"yaml-parse-error","analyzedSha":"bdb87aeaa4c4ff27c0ba643c1c77b21bf2ef4013","analyzedAt":"2026-09-16T02:53:35.741Z","contentChangedAt":"2026-09-16T02:53:35.741Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}