risingwavelabs/risingwave · error · anyhow::Error

env variable `RW_META_ADDR` not found. For `./risedev d` us

Error message

env variable `RW_META_ADDR` not found.

For `./risedev d` use cases, please do the following:
* use `./risedev ctl` to use risectl.

For production use cases,
* please set `RW_META_ADDR` to the address of the meta node.

Note: the default value of `RW_META_ADDR` is 'http://127.0.0.1:5690'.

What it means

MetaService::from_env reads RW_META_ADDR to learn where the meta node's gRPC endpoint lives. If the variable is absent, risectl bails with guidance: local users should use `./risedev ctl` (which sets it), and production users must set RW_META_ADDR to the meta node address. The default port would be 5690 but no default is applied automatically.

Source

Thrown at src/ctl/src/common/meta_service.rs:51

    ///
    /// * `RW_META_ADDR`: meta service address
    pub fn from_env() -> Result<Self> {
        let meta_addr = match env::var("RW_META_ADDR") {
            Ok(url) => {
                tracing::info!("using meta addr from `RW_META_ADDR`: {}", url);
                url
            }
            Err(_) => {
                const MESSAGE: &str = "env variable `RW_META_ADDR` not found.

For `./risedev d` use cases, please do the following:
* use `./risedev ctl` to use risectl.

For production use cases,
* please set `RW_META_ADDR` to the address of the meta node.

Note: the default value of `RW_META_ADDR` is 'http://127.0.0.1:5690'.";
                bail!(MESSAGE);
            }
        };
        Ok(Self { meta_addr })
    }

    /// Create meta client from options, and register as rise-ctl worker
    pub async fn create_meta_client(&self) -> Result<MetaClient> {
        let (client, _) = MetaClient::register_new(
            self.meta_addr.parse()?,
            WorkerType::RiseCtl,
            &get_new_ctl_identity(),
            Property::default(),
            Arc::new(MetaConfig::default()),
        )
        .await;
        let worker_id = client.worker_id();
        tracing::info!("registered as RiseCtl worker, worker_id = {}", worker_id);
        Ok(client)

View on GitHub (pinned to 6469eb736d)

Solutions

Use `./risedev ctl` instead of invoking risectl binaries directly — it sets RW_META_ADDR for you.
Export RW_META_ADDR=http://127.0.0.1:5690 (or the actual meta node address).
In production, set RW_META_ADDR to the meta node's advertised address in the deployment environment.

Example fix

// before
risingwave risectl table list   # no RW_META_ADDR
// after
export RW_META_ADDR="http://127.0.0.1:5690"
risingwave risectl table list

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.RW_META_ADDR) { throw new Error("RW_META_ADDR not set; use ./risedev ctl or export RW_META_ADDR=http://127.0.0.1:5690"); }

Try / catch

connectMeta().catch(e => {
  if (String(e).includes("RW_META_ADDR")) console.error("export RW_META_ADDR to your meta node address");
  else throw e;
});

Prevention

Use `./risedev ctl` which sets RW_META_ADDR automatically
Export RW_META_ADDR in deployment manifests / shell profiles
Remember the default is http://127.0.0.1:5690 — set it explicitly if meta runs elsewhere

When it happens

Trigger: Invoking risectl binaries directly (not via ./risedev ctl) without RW_META_ADDR exported; running in an environment where the var was not propagated; meta node running on a non-default port without the env var set.

Common situations: Fresh terminal after starting the cluster; CI or container where env vars were not passed through; production deployment where the meta address differs from 127.0.0.1:5690 and was never exported.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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