vectordotdev/vector · error

Paths must always start with a leading forward slash (`/`).

Error message

Paths must always start with a leading forward slash (`/`).

What it means

`Renderer::write` in lib/docs-renderer (used to assemble Vector's generated component documentation as JSON) treats `path` as a JSON-pointer-style path and requires it to start with `/`. A path without the leading slash has no defined root anchor for the segment walk, so the method panics immediately as a programmer-error assertion. The contract is spelled out in the `# Panics` section of the doc comment directly above the check.

Source

Thrown at lib/docs-renderer/src/renderer.rs:67

    /// The path follows the form of `/part1/part/.../partN`, where each slash-separated segment
    /// represents a nested object within the overall object hierarchy. For example, a path of
    /// `/root/nested/key2` would map to the value "weee!" if applied against the following JSON
    /// object:
    ///
    ///   { "root": { "nested": { "key2": "weee!" } } }
    ///
    /// # Panics
    ///
    /// If the path does not start with a forward slash, this method will panic. Likewise, if the
    /// path is _only_ a forward slash (aka there is no segment to describe the key within the
    /// object to write the value to), this method will panic.
    ///
    /// If any nested object within the path does not yet exist, it will be created. If any segment,
    /// other than the leaf segment, points to a value that is not an object/map, this method will
    /// panic.
    pub fn write<V: Into<Value>>(&mut self, path: &str, value: V) {
        if !path.starts_with('/') {
            panic!("Paths must always start with a leading forward slash (`/`).");
        }

        self.with_mut_object(|map| {
            // Split the path, and take the last element as the actual map key to write to.
            let mut segments = path.split('/').collect::<VecDeque<_>>();
            let key = segments.pop_back().expect("Path must end with a key.");

            // Iterate over the remaining elements, traversing into the root object one level at a
            // time, based on using `token` as the map key. If there's no map at the given key,
            // we'll create one. If there's something other than a map, we'll panic.
            let mut destination = map;
            while let Some(segment) = segments.pop_front() {
                if destination.contains_key(segment) {
                    match destination.get_mut(segment) {
                        Some(Value::Object(next)) => {
                            destination = next;
                            continue;
                        }

View on GitHub (pinned to 3708c39b12)

Solutions

1. Prefix the path with a forward slash: `renderer.write("/name", value)`.
2. Centralize path construction in a helper that always prepends `/` (e.g. `format!("/{key}")`) so callers cannot pass bare keys.
3. If you meant to replace the entire document, use `replace_root`/`clear`-style APIs instead of a malformed root path.

Example fix

// before
renderer.write("component_name", Value::String("demo".into()));

// after
renderer.write("/component_name", Value::String("demo".into()));

assert!(path.starts_with('/'), "Renderer paths must be rooted: {path}");
renderer.write(path, value);

fn is_rooted_path(p: &str) -> bool { p.starts_with('/') }

When it happens

Trigger: Calling `renderer.write("name", value)` or `renderer.write("root/nested/key", value)` instead of `renderer.write("/name", value)`. Any `write` where the first character is not `/`, including empty-string paths.

Common situations: Contributing generated docs where a template or data-collection step formats paths without the leading slash; refactoring code that previously joined path segments without a root element; copy-pasting a path from JSON examples that omit the root slash.

Related errors

• Only leaf nodes should be allowed to be non-object values.
• path and query should never fail to parse
• Serializer does not support JSON
• Reader encountered unrecoverable error: {e:?}
• Key is not found: {:?}

AI-assisted analysis of vectordotdev/vector@3708c39b12 (2026-08-20). Data as JSON: /api/errors/7c4d5a4749f48123. Report an issue: GitHub.