databendlabs/databend · error

invalid peer raft addr

Error message

invalid peer raft addr: {}

What it means

metasrv cluster import parses the peer raft address into an http URL to build a grpc Endpoint. If the first address in `addrs` cannot be parsed as host:port (no host or no port), the endpoint cannot be constructed and this error is thrown with the offending address.

Solutions

1. Check the first entry of the addresses passed to import; ensure it is a valid 'host:port' pair with a numeric port
2. Fix the address list or CLI flag (e.g. --raft-addr '127.0.0.1:9191') and re-run the import
3. For IPv6 use bracketed form 'http://[::1]:9191' style input so Url::parse and port extraction succeed
4. Print/echo the parsed address in your script to confirm what metactl actually received

Example fix

// before
metactl --import --raft-addr 127.0.0.1
// after
metactl --import --raft-addr 127.0.0.1:9191

fn validate_raft_addr(addr: &str) -> Result<(), String> {
    let url = url::Url::parse(&format!("http://{}", addr))
        .map_err(|e| format!("invalid addr '{}': {}", addr, e))?;
    if url.host_str().is_none() || url.port().is_none() {
        return Err(format!("addr '{}' must be host:port", addr));
    }
    Ok("")
}
// call before invoking metactl import with --raft-addr

When it happens

Trigger: Running `metactl` import with a --raft-addr (or peers list) whose first entry lacks a host, lacks a port, or is otherwise malformed (e.g. '127.0.0.1' without ':9191', a hostname with invalid characters).

Common situations: Config mistakes when migrating meta data: copy-pasting a node id or address list, forgetting the port, using IPv6 addresses without brackets, or leaving a placeholder value in a script.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Failed to create client
• Failed to get metrics
• Lua execution error
• no metasrv running on
• node id ( ) has to be one of cluster member( )

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/9b6714d5f5800674. Report an issue: GitHub.

Appendix: source

Thrown at src/meta/control/src/import.rs:169

        let id_addrs: Vec<&str> = peer.split('=').collect();
        if id_addrs.len() != 2 {
            return Err(anyhow::anyhow!("invalid peer str: {}", peer));
        }
        let id = u64::from_str(id_addrs[0])?;

        let addrs: Vec<&str> = id_addrs[1].split(',').collect();
        if addrs.len() > 2 || addrs.is_empty() {
            return Err(anyhow::anyhow!(
                "require 1 or 2 addresses in peer str: {}",
                peer
            ));
        }
        let url = Url::parse(&format!("http://{}", addrs[0]))?;
        let endpoint = match (url.host_str(), url.port()) {
            (Some(addr), Some(port)) => Endpoint::new(addr, port),
            _ => {
                return Err(anyhow::anyhow!("invalid peer raft addr: {}", addrs[0]));
            }
        };

        let node = Node::new(id, endpoint.clone());
        eprintln!("new cluster node:{}", node);

        nodes.insert(id, node);
    }

    if nodes.is_empty() {
        return Ok(nodes);
    }

    eprintln!("new cluster: {:?}", nodes);

    if !nodes.contains_key(&id) {
        return Err(anyhow::anyhow!(
            "node id ({}) has to be one of cluster member({:?})",

View on GitHub (pinned to 288d84d76e)