risingwavelabs/risingwave · error

invalid listen address

Error message

invalid listen address

What it means

RisingWave's MetaNodeOpts::meta_addr builds the meta node's advertised address by prefixing `http://` onto the configured `listen_addr` and parsing it into a URL. If `listen_addr` is not a valid `host:port` (or full URL) string, `.parse()` returns Err and the `.expect("invalid listen address")` panics. It is a startup-time configuration sanity check: the process cannot advertise itself to peers without a parseable address.

Source

Thrown at src/meta/node/src/lib.rs:218

    )]
    pub temp_secret_file_dir: String,

    /// Address of the serverless backfill controller.
    /// Needed if meta receives a streaming job with serverless backfill enabled.
    /// Feature disabled by default.
    #[clap(long, env = "RW_SBC_ADDR", default_value = "")]
    pub serverless_backfill_controller_addr: String,
}

impl risingwave_common::opts::Opts for MetaNodeOpts {
    fn name() -> &'static str {
        "meta"
    }

    fn meta_addr(&self) -> MetaAddressStrategy {
        format!("http://{}", self.listen_addr)
            .parse()
            .expect("invalid listen address")
    }
}

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;

use risingwave_common::config::{MetaBackend, RwConfig, load_config};
use tracing::info;

/// Start meta node
pub fn start(
    opts: MetaNodeOpts,
    shutdown: CancellationToken,
) -> Pin<Box<dyn Future<Output = ()> + Send>> {
    // WARNING: don't change the function signature. Making it `async fn` will cause
    // slow compile in release mode.
    Box::pin(async move {

View on GitHub (pinned to 6469eb736d)

Solutions

1. Set `--listen-addr` (or env `RW_LISTEN_ADDR`) to a valid `host:port` value, e.g. `127.0.0.1:5690`.
2. Check for empty or unexpanded shell/env variables in your launch script and quote/expand them correctly.
3. Remove any accidental scheme or path from the value; the code already prepends `http://`.
4. If the panic comes from programmatic use of `meta_addr`, validate/construct `listen_addr` with a SocketAddr parse before calling it.

Example fix

// before
RW_LISTEN_ADDR="${META_HOST}"
// after
RW_LISTEN_ADDR="${META_HOST}:5690"  # ensure host:port, e.g. 127.0.0.1:5690

fn validate_listen_addr(addr: &str) -> Result<(), String> {
    if addr.trim().is_empty() {
        return Err("listen address is empty".into());
    }
    addr.parse::<std::net::SocketAddr>()
        .map(|_| ())
        .map_err(|e| format!("invalid listen address '{addr}': {e}"))
}

fn is_valid_listen_addr(addr: &str) -> bool {
    addr.parse::<std::net::SocketAddr>().is_ok()
}

When it happens

Trigger: Calling `meta_addr()` (invoked during meta node startup via the `Opts` trait) when `--listen-addr`/`RW_LISTEN_ADDR` contains a malformed value such as an empty string, a bare hostname with no port, a value with an invalid port (e.g. `127.0.0.1:99999`), or characters not allowed in a URL authority.

Common situations: Typos in CLI flags or env files (e.g. `RW_LISTEN_ADDR=localhost:port`), template/CI variables left unexpanded (`${LISTEN_ADDR}`), empty string defaults, or copy-pasting an address including a scheme or path that breaks the `host:port` form.

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

• sql endpoint is required
• total_memory_bytes {} is larger than the total memory availa
• parallelism should not be zero
• The total memory size ({}) is too small. It must be at least
• reserved memory ({}) >= total memory ({}).

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