vectordotdev/vector · error

Expected to be a YAML mapping

Error message

Expected {description} to be a YAML mapping

What it means

`yaml_mapping` coerces a YAML node to a mapping with a human-readable description of what was expected. If the node is a scalar, sequence, or null instead of a mapping, it throws this error naming the description (e.g. "source example", "sink configuration").

Solutions

1. Convert the offending YAML node to a mapping (`key: value` pairs) matching the described structure.
2. If the root document is a list, restructure it into a single mapping with the component-type section at the root.
3. Give component entries under `sources:`/`transforms:`/`sinks:` full config mappings, not scalars.

Example fix

// before
sources:
  - my_source

// after
sources:
  my_source:
    type: my_source

function assertMapping(node, description) {
  if (node === null || Array.isArray(node) || typeof node !== 'object') {
    throw new Error(`Expected ${description} to be a YAML mapping`);
  }
}

function isYamlMapping(node) {
  return typeof node === 'object' && node !== null && !Array.isArray(node);
}

When it happens

Trigger: Any of `wrap_source`, `wrap_transform`, or `wrap_sink` passing a YAML node that is not a mapping: the root document is a list/scalar, the section value is a list, or a component entry under `sources`/`transforms`/`sinks` is a scalar.

Common situations: Example YAML uses `- item` list syntax where a mapping is required; the file was truncated or contains only a comment/scalar; a component key was given a value like `true` or a string instead of a config block.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• has no component identifier
• `duration` should be an i64
• `error` should be an i64
• `parent_id` should be an i64
• Sink example has no sinks section

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

Appendix: source

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

        ),
        (YamlValue::String("inputs".to_owned()), yaml_list([input])),
    ]))
}

fn yaml_list<'a>(values: impl IntoIterator<Item = &'a str>) -> YamlValue {
    YamlValue::Sequence(
        values
            .into_iter()
            .map(|value| YamlValue::String(value.to_owned()))
            .collect(),
    )
}

fn yaml_mapping(value: &YamlValue, description: &str) -> Result<Mapping> {
    value
        .as_mapping()
        .cloned()
        .ok_or_else(|| anyhow!("Expected {description} to be a YAML mapping"))
}

fn mapping_value<'a>(mapping: &'a Mapping, key: &str) -> Option<&'a YamlValue> {
    mapping.get(YamlValue::String(key.to_owned()))
}

fn mapping_key(mapping: &Mapping, description: &str) -> Result<String> {
    mapping
        .keys()
        .find_map(YamlValue::as_str)
        .map(str::to_owned)
        .ok_or_else(|| anyhow!("{description} has no component identifier"))
}

fn vector_binary(repo_root: &Path) -> Result<PathBuf> {
    if let Some(vector_bin) = std::env::var_os("VECTOR_BIN") {
        return Ok(PathBuf::from(vector_bin));
    }

View on GitHub (pinned to bdb87aeaa4)