influxdata/influxdb · error · Error

provided parameter (' ') could not be converted to a…

Error message

provided parameter ('{name}') could not be converted to a statment parameter

What it means

Error::ConvertQueryParam is raised when a caller-supplied parameter value cannot be converted into a query statement parameter; the parameter's name is included and the underlying iox_query_params::Error is the source. It is a type/conversion failure between the caller's value and the query parameter model.

Solutions

Check the parameter's value type against the expected statement parameter type and convert it explicitly before binding.
Inspect the source iox_query_params::Error for the exact conversion that failed.
Validate parameters against the query schema before invoking the client call.

Example fix

// before
params.insert("limit".into(), json!("10")); // string where int expected
// after
params.insert("limit".into(), json!(10));

Defensive patterns

Strategy: validation

Validate before calling

// check each bind param converts before calling the client
fn check_param(name: &str, v: &QueryValue) -> Result<(), String> {
    // ensure value kind matches the statement parameter type expected by the query
    v.to_statement_param().map(|_| ()).map_err(|e| format!("param '{name}': {e}"))
}

Type guard

fn is_query_value(v: &serde_json::Value) -> bool {
    matches!(v, serde_json::Value::Number(_) | serde_json::Value::String(_) | serde_json::Value::Bool(_))
}

Try / catch

match client.query_with_params(sql, params).await {
    Err(Error::ConvertQueryParam { name, .. }) => Err(anyhow!("fix bind param '{name}'")),
    other => other,
}

Prevention

Coerce JSON-derived values to expected types before binding.
Keep bind parameter types aligned with the query template schema.
Log parameter names/types when query building fails.

When it happens

Trigger: Calling client query APIs with bind parameters whose values are not representable as statement parameters (e.g. wrong type for a $param, unsupported value kind passed through influxdb3_types query parameter conversion).

Common situations: Passing JSON-derived values (strings where ints are expected, nested objects) as bind parameters; schema changes in the query template no longer matching parameter types.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/1d7c6824ab56b1dd. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_client/src/lib.rs:37

use influxdb3_types::http::*;
pub use influxdb3_types::write::Precision;

/// Primary error type for the [`Client`]
#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("base URL error: {}", reqwest_description(.0))]
    BaseUrl(#[source] reqwest::Error),

    #[error("request URL error: {0}")]
    RequestUrl(#[from] url::ParseError),

    #[error("failed to read the API response bytes: {}", reqwest_description(.0))]
    Bytes(#[source] reqwest::Error),

    #[error("failed to serialize the request body: {0}")]
    RequestSerialization(#[source] serde_json::Error),

    #[error(
        "provided parameter ('{name}') could not be converted \
        to a statment parameter"
    )]
    ConvertQueryParam {
        name: String,
        #[source]
        source: iox_query_params::Error,
    },

    #[error("invalid UTF8 in response: {0}")]
    InvalidUtf8(#[from] FromUtf8Error),

    #[error("failed to parse JSON response: {}", reqwest_description(.0))]
    Json(#[source] reqwest::Error),

    #[error("failed to parse plaintext response: {}", reqwest_description(.0))]
    Text(#[source] reqwest::Error),

View on GitHub (pinned to 06200ef96b)