Run `make generate-docs` locally to update your branch and…

Error message

Run `make generate-docs` locally to update your branch and commit the changes.

What it means

`vdev check generated-docs` (component examples) detects that generated component example files under the examples directory are out of sync with the docs metadata in the current branch. It prints the changed files and bails, instructing the developer to regenerate and commit them.

Solutions

Run `make generate-docs` locally.
Commit the regenerated example files.
Re-run `make check-generated-docs` to confirm it passes.

Defensive patterns

Strategy: validation

Validate before calling

git status --porcelain | grep '^ M' # must be empty after running make generate-docs

Prevention

Always run `make generate-docs` after editing component docs or metadata.
Add the generated-docs check to a pre-push hook (see AGENTS.md).
Commit generated files in the same PR as the source change.

When it happens

Trigger: Running the generated-docs check after editing component docs/metadata without re-running `make generate-docs`, leaving files under the examples dir modified relative to git.

Common situations: A contributor adds a config option or edits component documentation comments, then CI fails because the auto-generated example configs were not regenerated.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at vdev/src/commands/check/component_examples.rs:49

        let docs = docs_json::render_docs(&repo_root)?;
        let docs: Value =
            serde_json::from_slice(&docs).context("CUE did not produce valid JSON")?;

        validate_examples(&repo_root, &repo_root.join(EXAMPLES_DIR), &docs)
    }
}

fn check_generated_examples() -> Result<()> {
    let changed_examples = component_example_changes(git::get_files_changed_from_head()?);
    if changed_examples.is_empty() {
        return Ok(());
    }

    println!("Found out-of-sync component examples in this branch:");
    for file in changed_examples {
        println!(" - {file}");
    }
    bail!("Run `make generate-docs` locally to update your branch and commit the changes.")
}

fn component_example_changes(files: Vec<String>) -> Vec<String> {
    files
        .into_iter()
        .filter(|file| file.starts_with(EXAMPLES_DIR))
        .collect()
}

struct ValidationCase {
    key: String,
    config: YamlValue,
}

fn validate_examples(repo_root: &Path, examples_dir: &Path, docs: &Value) -> Result<()> {
    let (cases, total, skipped) = validation_cases(examples_dir, docs)?;
    let vector_bin = vector_binary(repo_root)?;
    let jobs = std::env::var("VALIDATE_CONFIG_EXAMPLES_JOBS")

View on GitHub (pinned to bdb87aeaa4)