The lints documentation is out-of-date. Run `cargo lint-docs

Error message

The lints documentation is out-of-date. Run `cargo lint-docs` to update it.

What it means

xtask-lint-docs regenerates the lints documentation from Cargo's lint definitions. In --check mode it compares the freshly generated content against the on-disk file; if they differ (docs are stale), it bails instructing the user to run `cargo lint-docs` to regenerate. This keeps docs in sync with lint definitions.

Source

Thrown at crates/xtask-lint-docs/src/main.rs:89

    if !warn.is_empty() {
        add_level_section(LintLevel::Warn, &warn, &mut buf)?;
    }
    if !deny.is_empty() {
        add_level_section(LintLevel::Deny, &deny, &mut buf)?;
    }
    if !forbid.is_empty() {
        add_level_section(LintLevel::Forbid, &forbid, &mut buf)?;
    }

    buf.push_str(&lint_docs);

    writeln!(buf)?;
    writeln!(buf, "[`package.rust-version`]: rust-version.md")?;

    if check {
        let old = std::fs::read_to_string(lint_docs_path())?;
        if old != buf {
            anyhow::bail!(
                "The lints documentation is out-of-date. Run `cargo lint-docs` to update it."
            );
        }
    } else {
        std::fs::write(lint_docs_path(), buf)?;
    }
    Ok(())
}

fn lint_groups(buf: &mut String) -> anyhow::Result<()> {
    writeln!(
        buf,
        r#"## Lint groups

Cargo has the concept of a "lint group",
where you can toggle several warnings through one name."#
    )?;
    let (max_name_len, max_desc_len) = cargo::diagnostics::LINT_GROUPS

View on GitHub (pinned to 42eee92bc9)

Solutions

Run `cargo lint-docs` (without --check) to regenerate, then commit the updated file.
If the diff is unexpected, inspect the changed lint definitions to ensure the regeneration is correct.

Example fix

// before
cargo lint-docs --check   # fails
// after
cargo lint-docs           # regenerate
git add src/doc/src/reference/lints.md
git commit -m "doc: update lints"

Defensive patterns

Strategy: validation

Validate before calling

// Run generation then compare to keep docs in sync
let _ = Command::new("cargo").arg("lint-docs").status()?;
// commit if changed; the --check variant then passes

Type guard

null

Try / catch

null

Prevention

Regenerate lint docs in the same PR that changes lint definitions.
Run `cargo lint-docs --check` in CI to catch drift.

When it happens

Trigger: Running `cargo lint-docs --check` after lint definitions/levels changed but before regenerating the docs file. The generated buffer differs from the committed file, so the check fails.

Common situations: Editing lint registrations or levels in source without updating the docs; CI lint-docs check on a PR that touches lints; rebasing across a lint change.

Related errors

AI-assisted analysis of rust-lang/cargo@42eee92bc9 (2026-08-11). Data as JSON: /api/errors/a56586f884def875. Report an issue: GitHub.