risingwavelabs/risingwave · error · MetaAddressStrategyParseError

there should be only one load balance address

Error message

there should be only one load balance address

What it means

When parsing a meta address strategy, RisingWave allows either plain per-node addresses or exactly one load-balance (LB) address that fronts all meta nodes. `MultipleLoadBalance` is returned if more than one address in the list is marked as load-balanced, because the strategy would be ambiguous — it cannot tell which LB address the meta nodes sit behind.

Source

Thrown at src/common/src/util/meta_addr.rs:36

use itertools::Itertools;

const META_ADDRESS_LOAD_BALANCE_MODE_PREFIX: &str = "load-balance+";

/// The strategy for meta client to connect to meta node.
///
/// Used in the command line argument `--meta-address`.
#[derive(Debug, Eq, PartialEq, Clone)]
pub enum MetaAddressStrategy {
    LoadBalance(http::Uri),
    List(Vec<http::Uri>),
}

/// Error type for parsing meta address strategy.
#[derive(thiserror::Error, Debug, thiserror_ext::ContextInto)]
pub enum MetaAddressStrategyParseError {
    #[error("empty meta addresses")]
    Empty,
    #[error("there should be only one load balance address")]
    MultipleLoadBalance,
    #[error("failed to parse meta address `{1}`: {0}")]
    UrlParse(#[source] http::uri::InvalidUri, String),
}

impl FromStr for MetaAddressStrategy {
    type Err = MetaAddressStrategyParseError;

    fn from_str(meta_addr: &str) -> Result<Self, Self::Err> {
        if let Some(addr) = meta_addr.strip_prefix(META_ADDRESS_LOAD_BALANCE_MODE_PREFIX) {
            // UFCS pins this to `itertools::Itertools::exactly_one`; a future
            // stabilization of `Iterator::exactly_one` (rust#48919) would otherwise
            // make the bare method call ambiguous / silently rebind.
            let addr = Itertools::exactly_one(addr.split(','))
                .map_err(|_| MetaAddressStrategyParseError::MultipleLoadBalance)?;

            let uri = addr.parse().into_url_parse(addr)?;

View on GitHub (pinned to 6469eb736d)

Solutions

1. Keep at most one load-balanced address in the list; remove the extras
2. If multiple LB endpoints must be reachable, pick one canonical LB address and point the rest of the topology at it, or list individual node addresses instead
3. Mixing is not supported: use either all direct node addresses plus at most one LB address — verify with the strategy grammar in src/common/src/util/meta_addr.rs

Example fix

// before
--meta-address "lb://lb-a:5690,lb://lb-b:5690"
// after
--meta-address "lb://lb-a:5690"   // exactly one LB address

// count load-balanced entries before parsing
let lb_count = raw.split(',')
    .map(str::trim)
    .filter(|a| a.starts_with("lb://"))
    .count();
if lb_count > 1 {
    return Err("at most one lb:// address is allowed in the meta address list");
}

When it happens

Trigger: Passing a meta address list containing two or more LB-flagged addresses (e.g. `lb://lb1,lb://lb2` or two addresses both wrapped in the LB scheme/marker) to `MetaAddressStrategy::from_str` via `--meta-address`.

Common situations: Deployments fronted by multiple load balancers (e.g. one per region) where operators list all LB endpoints; copy-pasting LB endpoints from different environments; mixing direct node addresses and several LB addresses in one flag.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• empty meta addresses
• failed to parse meta address `{1}`: {0}
• unrecognized configs: {:?}
• Unsupported parallelism: {0}
• Unsupported strategy: {0}

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/9559caea56c71e8a. Report an issue: GitHub.