vectordotdev/vector · error

FunctionDoc serialization should not fail

Error message

FunctionDoc serialization should not fail

What it means

The vrl doc-builder CLI converts VRL function docs into a `FunctionDoc` structure and serializes it to JSON with `serde_json::to_string`, panicking with this message on failure. JSON serialization of this plain-data struct is expected to be infallible; the panic guards against a serde bug or an unserializable field type sneaking in.

Solutions

1. Inspect the newly added/changed function docs (doc comments/args) for values that fail JSON serialization (NaN/Inf floats, non-string map keys)
2. Run the builder with RUST_BACKTRACE=1 to confirm which field fails, or temporarily replace expect with a match to print the serde error
3. Ensure serde/serde_json versions are consistent across the workspace (`cargo update`)
4. If a doc field is genuinely fallible, change `FunctionDoc` to serialize via a fallible path and propagate the error with `?`

Example fix

// before
serde_json::to_string(&built).expect("FunctionDoc serialization should not fail")
// after
serde_json::to_string(&built)
    .context("FunctionDoc serialization should not fail")?

let json = serde_json::to_string(&built);
assert!(json.is_ok(), "FunctionDoc must be JSON-serializable: {:?}", json.err());

fn is_finite_doc_value(v: &serde_json::Value) -> bool {
    match v { serde_json::Value::Number(n) => n.is_finite(), _ => true }
}

match serde_json::to_string(&built) {
    Ok(s) => println!("{s}"),
    Err(e) => eprintln!("doc serialization failed: {e}"), // surface real cause
}

When it happens

Trigger: Running `doc-builder` without `--minify` (pretty variant at line 38 uses to_string; this is the minified `to_string` path) when `serde_json::to_string(&built)` returns Err — e.g. a `FunctionDoc` field containing a map with non-string keys or a NaN float introduced by a new function definition.

Common situations: Adding a new VRL function whose docs contain data serde_json cannot serialize (odd key types, non-finite floats); serde version mismatches in the workspace.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Could not convert concurrency to JSON
• Bad fragment filename
• Could not convert HTTP status code to JSON
• Could not convert number to JSON
• Could not convert time zone to JSON

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

Appendix: source

Thrown at lib/vector-vrl/doc-builder/src/main.rs:38

    minify: bool,

    /// File extension for generated files (directory mode only)
    #[arg(short, long, default_value = "json", requires = "output")]
    extension: String,
}

#[allow(clippy::print_stdout)]
fn main() -> Result<()> {
    let cli = <Cli as clap::Parser>::parse();
    let functions = vector_vrl_functions::all_without_vrl_stdlib();
    if let Some(output) = &cli.output {
        document_functions_to_dir(&functions, output, &cli.extension)?;
    } else {
        let built = build_functions_doc(&functions);
        if cli.minify {
            println!(
                "{}",
                serde_json::to_string(&built).expect("FunctionDoc serialization should not fail")
            );
        } else {
            println!(
                "{}",
                serde_json::to_string_pretty(&built)
                    .expect("FunctionDoc serialization should not fail")
            );
        }
    }
    Ok(())
}

View on GitHub (pinned to bdb87aeaa4)