vectordotdev/vector · error

Deprecation fragment

Error message

Deprecation fragment {} must begin with YAML frontmatter (---)

What it means

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.

Solutions

1. Open the fragment file in the error and add a YAML frontmatter block starting with `---` as the very first line.
2. Remove any BOM or stray characters (including HTML comments) before the opening `---`.
3. Compare against an existing valid deprecation fragment and match its header structure, then re-run the check.

Example fix

# before
deprecates the `foo` transform.

# after
---
date: 2026-09-15
component: transform/foo
---
deprecates the `foo` transform.

def has_frontmatter(text):
    return text.lstrip('\ufeff \t\n\r').startswith('---')

content = open(path, encoding='utf-8-sig').read()
assert has_frontmatter(content), f"{path} must start with YAML frontmatter"

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Deprecation fragment
• Deprecation fragment
• Conflicting enacted entry for
• Duplicate deprecation fragments for `what
• Duplicate enacted entry for

AI-assisted analysis of vectordotdev/vector@bdb87aeaa4 (2026-09-16). Data as JSON: /api/errors/294fce7d89cee013. Report an issue: GitHub.

Appendix: source

Thrown at vdev/src/utils/deprecation.rs:203

    }

    Ok(DeprecationEntry {
        filename,
        what: fm.what.trim().to_string(),
        deprecated_since: fm.deprecated_since,
        description: body.trim().to_string(),
    })
}

/// Split the raw file contents into the frontmatter string and the body.
/// The file must begin with `---`, and have a closing `---` on its own line.
fn split_frontmatter<'a>(content: &'a str, path: &Path) -> Result<(&'a str, &'a str)> {
    let content = content.trim_start();
    // Advance past the opening `---` (and optional trailing whitespace on that line)
    let after_open = content
        .strip_prefix("---")
        .ok_or_else(|| {
            anyhow!(
                "Deprecation fragment {} must begin with YAML frontmatter (---)",
                path.display()
            )
        })?
        .trim_start_matches([' ', '\t'])
        .trim_start_matches('\n');

    let (frontmatter, rest) = after_open.split_once("\n---").ok_or_else(|| {
        anyhow!(
            "Deprecation fragment {} has unclosed frontmatter",
            path.display()
        )
    })?;
    let rest = rest.trim_start_matches(['\r', '\n']);
    let body = rest.trim_start_matches(['\r', '\n']);

    Ok((frontmatter, body))
}

View on GitHub (pinned to bdb87aeaa4)