vectordotdev/vector · error

Deprecation fragment

Error message

Deprecation fragment {}: `what` field must not be empty

What it means

Each deprecation fragment must carry a non-empty `what` field identifying the deprecated feature. After parsing frontmatter, `parse_deprecation_fragment` trims the value and bails if it is empty, since an unnamed deprecation cannot be tracked or published.

Solutions

1. Open the file named in the error and set a descriptive `what` value naming the deprecated item
2. Ensure there is no leading/trailing whitespace making it appear empty after trim
3. Validate the fragment against existing examples in changelog.d
4. Re-run the deprecation check after fixing

Example fix

// before
---
what: ""
removed_in: 0.48.0
---
// after
---
what: "kafka source `encoding` option"
removed_in: 0.48.0
---

fn valid_frontmatter(raw: &str) -> bool {
    let fm = raw.trim_start_matches("---")
        .split("---").next().unwrap_or("");
    fm.lines().any(|l| l.starts_with("what:") && !l.trim_start_matches("what:").trim().is_empty())
}
assert!(valid_frontmatter(fragment_text));

When it happens

Trigger: Adding a fragment file in changelog.d with `what:` empty, whitespace-only, or omitted, then running the deprecation tooling that parses fragments.

Common situations: Creating a fragment from a template and forgetting to fill in `what`; accidentally deleting the line during an edit; YAML frontmatter with `what: ""` from scripted generation.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Deprecation fragment
• Deprecation fragment
• Duplicate deprecation fragments for `what
• Duplicate enacted entry for
• Enacted entry ' ' has removed_in ( ) that is not in a later…

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

Appendix: source

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

}

fn parse_deprecation_fragment(path: &Path) -> Result<DeprecationEntry> {
    let filename = path
        .file_name()
        .and_then(|n| n.to_str())
        .unwrap_or("")
        .to_string();

    let raw =
        fs::read_to_string(path).with_context(|| format!("Failed to read {}", path.display()))?;

    let (frontmatter_str, body) = split_frontmatter(&raw, path)?;

    let fm: Frontmatter = serde_yaml::from_str(frontmatter_str)
        .with_context(|| format!("Failed to parse YAML frontmatter in {}", path.display()))?;

    if fm.what.trim().is_empty() {
        bail!(
            "Deprecation fragment {}: `what` field must not be empty",
            path.display()
        );
    }

    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)

View on GitHub (pinned to bdb87aeaa4)