risingwavelabs/risingwave · error · anyhow::Error

env variable `RW_HUMMOCK_URL` not found. * start the cluste

Error message

env variable `RW_HUMMOCK_URL` not found.

* start the cluster with shared storage:
- consider adding `use: minio` in the risedev config,
- or directly use `./risedev d for-ctl` to start the cluster.
* use `./risedev ctl` to use risectl.

For production use cases,
* please set `RW_HUMMOCK_URL` to the same address specified for the meta node.

What it means

HummockService::from_env requires the RW_HUMMOCK_URL environment variable; if it is unset the operation bails with a detailed message explaining how to get one (shared-storage cluster, `./risedev d for-ctl`, or setting the var manually for production). risectl cannot access Hummock state without knowing the storage backend location.

Source

Thrown at src/ctl/src/common/hummock_service.rs:86

                    return Err(anyhow!(
                        "only url starting with 'hummock+' is supported in risectl"
                    ));
                }
                tracing::info!("using Hummock URL from `RW_HUMMOCK_URL`: {}", url);
                url
            }
            Err(_) => {
                const MESSAGE: &str = "env variable `RW_HUMMOCK_URL` not found.
                    For `./risedev d` use cases, please do the following.
                    * start the cluster with shared storage:
                    - consider adding `use: minio` in the risedev config,
                    - or directly use `./risedev d for-ctl` to start the cluster.
                    * use `./risedev ctl` to use risectl.

                    For production use cases,
                    * please set `RW_HUMMOCK_URL` to the same address specified for the meta node.
                ";
                bail!(MESSAGE);
            }
        };

        Ok(Self {
            hummock_url,
            data_dir,
            heartbeat_handle: None,
            heartbeat_shutdown_sender: None,
            use_new_object_prefix_strategy,
        })
    }

    fn get_storage_opts(&self) -> StorageOpts {
        let mut opts = StorageOpts {
            share_buffer_compaction_worker_threads_number: 0,
            meta_cache_capacity_mb: 1,
            block_cache_capacity_mb: 1,
            meta_cache_shard_num: 1,

View on GitHub (pinned to 6469eb736d)

Solutions

Add `use: minio` to the risedev config so the cluster uses shared storage, then restart with `./risedev d`.
Or start the cluster with `./risedev d for-ctl`, which sets RW_HUMMOCK_URL automatically.
Or manually export RW_HUMMOCK_URL to the same state-store address configured on the meta node (with the hummock+ prefix).
Prefer `./risedev ctl` for local use, which wires up the env vars for you.

Example fix

// before
./risedev ctl hummock scan-table
// after
export RW_HUMMOCK_URL="hummock+minio://hummock01:hummock01@127.0.0.1:9301/hummock01"
./risedev ctl hummock scan-table

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.RW_HUMMOCK_URL) { throw new Error("RW_HUMMOCK_URL is not set; use ./risedev d for-ctl or export it manually"); }

Try / catch

runCtl().catch(e => {
  if (String(e).includes("RW_HUMMOCK_URL")) {
    console.error("Set RW_HUMMOCK_URL (hummock+...) or start with `./risedev d for-ctl`");
  } else throw e;
});

Prevention

Start dev clusters with shared storage (`use: minio`) so the var is meaningful
Use `./risedev ctl` wrapper instead of invoking binaries directly
Export RW_HUMMOCK_URL in shell profile / CI environment for production-like runs

When it happens

Trigger: Running risectl commands that need state-store access (e.g. hummock scan, table scan) in a shell where RW_HUMMOCK_URL was never exported — typically when the cluster was started without shared storage or in a different shell session.

Common situations: Cluster started with in-memory/local storage instead of minio; opening a fresh terminal without the env var; production deployment where the operator forgot to export RW_HUMMOCK_URL to match the meta node's state store.

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/6ddc8cb3ea0fe1a0. Report an issue: GitHub.