vectordotdev/vector · error

content between the title and `## Summary` is not allowed —…

Error message

content between the title and `## Summary` is not allowed — move it into `## Summary` or `## Migration`.

What it means

`parse_breaking_sections` rejects any non-whitespace prose between the H1 title line and the `## Summary` heading. This guards against hand-migrated free-form fragments whose body would silently disappear from the release CUE and upgrade guide. If the prefix before Summary contains visible content, it bails with this error telling the author to move the content into Summary or Migration.

Solutions

1. Move the prose between the title and `## Summary` into the `## Summary` section.
2. Alternatively move content describing upgrade steps into `## Migration`.
3. Ensure only blank lines remain between the title and `## Summary`.

Example fix

// before
# My change
This note explains the change.
## Summary
Summary text.
## Migration
Steps.
// after
# My change
## Summary
This note explains the change. Summary text.
## Migration
Steps.

let s_pos = after_title.find("## Summary").unwrap_or(0);
let prefix = &after_title[..s_pos];
if !prefix.trim().is_empty() {
    eprintln!("move prose between title and Summary into Summary or Migration");
}

if let Err(e) = parse_breaking_sections(text) {
    eprintln!("fragment structure: {e}");
}

When it happens

Trigger: Parsing a breaking fragment with any text, list items, or code blocks placed between the title line and the first `## Summary` heading.

Common situations: Pasting an old free-form breaking-change fragment (which was one blob of prose under the title) into the new format; writing an intro paragraph before the Summary heading.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• exactly one `## Migration` section is required
• exactly one `## Summary` section is required
• H1 title must not be empty
• invalid breaking fragment
• `## Summary` must not be empty

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

Appendix: source

Thrown at vdev/src/commands/changelog/mod.rs:153

    }
    if after_title.matches(MIGRATION_MARKER).count() != 1 {
        bail!("exactly one `## Migration` section is required");
    }
    let s_pos = after_title.find(SUMMARY_MARKER).unwrap();
    let m_pos = after_title.find(MIGRATION_MARKER).unwrap();
    if s_pos >= m_pos {
        bail!("`## Summary` must come before `## Migration`");
    }

    // Reject any prose between the H1 title and `## Summary`. Someone hand-migrating an
    // old free-form breaking fragment could carry over the previous body here and it
    // would silently disappear from both the release CUE and the upgrade guide.
    // Everything before Summary must be whitespace (`\n## Summary\n` starts with the
    // leading newline, so `s_pos` includes it).
    if let Some(prefix) = after_title.get(..s_pos)
        && !prefix.trim().is_empty()
    {
        bail!(
            "content between the title and `## Summary` is not allowed — move it into `## Summary` or `## Migration`."
        );
    }

    let summary = after_title
        .get(s_pos + SUMMARY_MARKER.len()..m_pos)
        .unwrap_or("")
        .trim()
        .to_string();
    let migration = after_title
        .get(m_pos + MIGRATION_MARKER.len()..)
        .unwrap_or("")
        .trim()
        .to_string();

    if summary.is_empty() {
        bail!("`## Summary` must not be empty");
    }

View on GitHub (pinned to bdb87aeaa4)