TDengine native agent supports only WebSocket connection str

Error message

TDengine native agent supports only WebSocket connection strings

What it means

normalize_connection_string parses the provided TDengine connection string and enforces that the agent only speaks WebSocket (ws/wss, with http/https auto-upgraded). Any other scheme — e.g. taos, jdbc:taos, or postgres — is rejected. This prevents accidentally pointing the WebSocket agent at a native/JDBC endpoint it cannot handle.

Source

Thrown at agents/drivers/tdengine/src/config.rs:99

fn normalize_connection_string(raw: &str, ssl: bool) -> Result<Url> {
    let trimmed = raw.trim();
    let normalized = if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "jdbc:TAOS-WS://") {
        format!("{}://{value}", if ssl { "wss" } else { "ws" })
    } else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "jdbc:TAOS-RS://") {
        format!("{}://{value}", if ssl { "wss" } else { "ws" })
    } else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "tdengine://") {
        format!("{}://{value}", if ssl { "wss" } else { "ws" })
    } else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "taosws://") {
        format!("{}://{value}", if ssl { "wss" } else { "ws" })
    } else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "taoswss://") {
        format!("wss://{value}")
    } else {
        trimmed.to_string()
    };
    let mut url = Url::parse(&normalized).with_context(|| "invalid TDengine connection string")?;
    if !matches!(url.scheme(), "ws" | "wss" | "http" | "https") {
        bail!("TDengine native agent supports only WebSocket connection strings");
    }
    if matches!(url.scheme(), "http") {
        url.set_scheme("ws").map_err(|_| anyhow::anyhow!("invalid TDengine HTTP connection string"))?;
    } else if matches!(url.scheme(), "https") {
        url.set_scheme("wss").map_err(|_| anyhow::anyhow!("invalid TDengine HTTPS connection string"))?;
    }
    remove_control_params(&mut url);
    Ok(url)
}

fn merge_query_params(url: &mut Url, raw: &str) {
    let raw = raw.trim().trim_start_matches('?');
    if raw.is_empty() {
        return;
    }
    let additions = url::form_urlencoded::parse(raw.as_bytes())
        .filter(|(key, _)| !is_control_param(key))
        .map(|(key, value)| (key.into_owned(), value.into_owned()))

View on GitHub (pinned to c0390bff16)

Solutions

Change the scheme to ws:// or wss:// (e.g. ws://host:6041)
http:// and https:// are accepted and auto-converted to ws/wss — prefer those if pointing at the REST/WebSocket port
Strip jdbc:TAOS-RS:// prefixes and convert the remainder into a ws:// URL

Example fix

// before
connection_string = "jdbc:TAOS-RS://tdengine:6041"
// after
connection_string = "ws://tdengine:6041"

Defensive patterns

Strategy: validation

Validate before calling

let url = url::Url::parse(&params.connection_string)?;
if !matches!(url.scheme(), "ws" | "wss" | "http" | "https") {
    return Err(anyhow!("use ws:// or wss:// scheme"));
}

Type guard

fn is_ws_scheme(s: &str) -> bool {
    url::Url::parse(s).map(|u| matches!(u.scheme(), "ws" | "wss" | "http" | "https")).unwrap_or(false)
}

Prevention

Normalize JDBC URLs before storing connection profiles
Default to ws://host:6041 for the WebSocket port
Reject taos:// schemes in UI input validation

When it happens

Trigger: Passing a connection string with a scheme other than ws/wss/http/https, such as 'taos://host:6030' or a legacy 'jdbc:TAOS-RS://...' URL, into ConnectParams.connection_string.

Common situations: Reusing a JDBC URL from an existing Java app, copying a native taos:// DSN from TDengine docs, or forgetting the ws:// prefix entirely.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/000432a5daf54749. Report an issue: GitHub.