risingwavelabs/risingwave · error

sql endpoint is required

Error message

sql endpoint is required

What it means

When the meta node's configured backend is `MetaBackend::Sql` (a generic SQL metadata store), the code unwraps `opts.sql_endpoint` with `.expect("sql endpoint is required")`. The `sql` backend needs a connection endpoint URL to reach the metadata database, so if `--sql-endpoint` was not provided, the meta node panics at startup instead of continuing without a usable store.

Source

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

        info!("> options: {:?}", opts);
        let config = load_config(&opts.config_path, &opts);
        info!("> config: {:?}", config);
        info!("> version: {} ({})", RW_VERSION, GIT_SHA);
        let listen_addr = opts.listen_addr.parse().unwrap();
        let dashboard_addr = opts.dashboard_host.map(|x| x.parse().unwrap());
        let prometheus_addr = opts.prometheus_listener_addr.map(|x| x.parse().unwrap());
        let meta_store_config = config.meta.meta_store_config.clone();
        let backend = match config.meta.backend {
            MetaBackend::Mem => {
                if opts.sql_endpoint.is_some() {
                    tracing::warn!("`--sql-endpoint` is ignored when using `mem` backend");
                }
                MetaStoreBackend::Mem
            }
            MetaBackend::Sql => MetaStoreBackend::Sql {
                endpoint: opts
                    .sql_endpoint
                    .expect("sql endpoint is required")
                    .expose_secret()
                    .clone(),
                config: meta_store_config,
            },
            MetaBackend::Sqlite => MetaStoreBackend::Sql {
                endpoint: format!(
                    "sqlite://{}?mode=rwc",
                    opts.sql_endpoint
                        .expect("sql endpoint is required")
                        .expose_secret()
                ),
                config: meta_store_config,
            },
            MetaBackend::Postgres => MetaStoreBackend::Sql {
                endpoint: format!(
                    "postgres://{}:{}@{}/{}{}",
                    opts.sql_username,
                    opts.sql_password.expose_secret(),

View on GitHub (pinned to 6469eb736d)

Solutions

1. Pass `--sql-endpoint <url>` (or set env `RW_SQL_ENDPOINT`) with the metadata database connection string when using backend `sql`.
2. Set `meta.backend = "mem"` (or omit it) in the config if you did not intend to use a SQL meta store.
3. If endpoint is provisioned via secret manager, verify the secret is mounted and exported into the process environment.
4. Check your config file's `[meta]` section matches the flags you actually pass.

Example fix

// before
./risingwave meta-node --backend sql
// after
./risingwave meta-node --backend sql --sql-endpoint "postgres://user:pass@host:5432/risingwave"

if [[ "${BACKEND}" == "sql" && -z "${RW_SQL_ENDPOINT:-}" ]]; then
  echo "error: --sql-endpoint / RW_SQL_ENDPOINT is required when backend=sql" >&2
  exit 1
fi

fn sql_endpoint_ready(backend: &str, endpoint: Option<&str>) -> bool {
    backend != "sql" || endpoint.map(|e| !e.trim().is_empty()).unwrap_or(false)
}

match config.meta.backend {
    MetaBackend::Sql if opts.sql_endpoint.is_none() => {
        eprintln!("--sql-endpoint is required when backend=sql");
        std::process::exit(1);
    }
    _ => {}
}

When it happens

Trigger: Starting the meta node with `--backend sql` (or `meta.backend = "sql"` in the config file) without also passing `--sql-endpoint` / env `RW_SQL_ENDPOINT`.

Common situations: Switching a deployment from the default `mem` backend to `sql` in the config file but forgetting to add the endpoint flag; secrets-managed env vars not propagated to the meta container; following an older runbook that predates the required endpoint flag.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• invalid listen address
• 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/bd2b39717037fe72. Report an issue: GitHub.