What causes "Transform example has no transforms section" in vectordotdev/vector?

Add a top-level `transforms:` mapping containing the transform key to the example YAML.

Transform example has no transforms section

Error message

Transform example has no transforms section

What it means

`wrap_transform` builds a validation topology for transform examples and requires the example YAML to have a top-level `transforms` mapping. If the key is missing, the transform key cannot be extracted and inputs cannot be wired to the validation source, so it throws this error.

Solutions

Add a top-level `transforms:` mapping containing the transform key to the example YAML.
Verify the example is registered as a transform example.
Check YAML indentation so `transforms:` sits at the document root.

Example fix

// before
my_transform:
  type: remap

// after
transforms:
  my_transform:
    type: remap

Defensive patterns

Strategy: validation

Validate before calling

const root = yaml.parse(exampleYaml);
if (!root || Array.isArray(root) || typeof root !== 'object' || typeof root.transforms !== 'object' || root.transforms === null) {
  throw new Error('transform example must have a top-level `transforms` mapping');
}

Type guard

function hasTransformsSection(root) {
  return typeof root === 'object' && root !== null && !Array.isArray(root) && typeof root.transforms === 'object' && root.transforms !== null;
}

Prevention

Use an existing transform example as the template for new transforms.
Check YAML indentation so `transforms:` is a root key.
Run the component example check in CI on every docs/config PR.

When it happens

Trigger: Running the component example check on an example file whose component YAML lacks a top-level `transforms` section (wrong root key, nested structure, or the file is not a transform example).

Common situations: A new transform's example was authored from a source or sink template; manual edits moved or renamed `transforms:`; YAML indentation accidentally nested `transforms` under another key.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

            YamlValue::String("_validate_sink".to_owned()),
            blackhole(&source_key),
        );
    }
    root.insert(
        YamlValue::String("sinks".to_owned()),
        YamlValue::Mapping(sinks),
    );
    Ok(YamlValue::Mapping(root))
}

fn wrap_transform(component_yaml: &YamlValue, component: &Value) -> Result<Option<YamlValue>> {
    let Some(source) = validation_source(component) else {
        return Ok(None);
    };
    let root = yaml_mapping(component_yaml, "transform example")?;
    let transforms = yaml_mapping(
        mapping_value(&root, "transforms")
            .ok_or_else(|| anyhow!("Transform example has no transforms section"))?,
        "transform example transforms",
    )?;
    let transform_key = mapping_key(&transforms, "transform example")?;
    let mut transform = yaml_mapping(
        mapping_value(&transforms, &transform_key)
            .ok_or_else(|| anyhow!("Transform {transform_key} is missing"))?,
        "transform configuration",
    )?;
    transform.insert(
        YamlValue::String("inputs".to_owned()),
        yaml_list(["_validate_source"]),
    );

    let named_outputs = route_outputs(&transform);
    let mut sinks = Mapping::new();
    if named_outputs.is_empty() {
        sinks.insert(
            YamlValue::String("_validate_sink".to_owned()),

View on GitHub (pinned to bdb87aeaa4)