risingwavelabs/risingwave · error · ConnectorError

`warehouse.path` must be set

Error message

`warehouse.path` must be set

What it means

Raised in `IcebergConnection::validate_connection` when `warehouse.path` is absent and the configured catalog is not a REST catalog. For non-REST (e.g. JDBC/Hive/Glue) catalogs the warehouse location is mandatory, so validation bails early. REST catalogs may omit it because the server can supply/resolve the warehouse.

Source

Thrown at src/connector/src/connector_common/connection.rs:209

                    None
                } else {
                    let url =
                        url.with_context(|| format!("Invalid warehouse path: {}", warehouse_path))?;
                    let bucket = url
                        .host_str()
                        .with_context(|| {
                            format!("Invalid s3 path: {}, bucket is missing", warehouse_path)
                        })?
                        .to_owned();
                    let root = url.path().trim_start_matches('/').to_owned();
                    Some((url.scheme().to_owned(), bucket, root))
                }
            }
            None => {
                if is_rest_catalog {
                    None
                } else {
                    bail!("`warehouse.path` must be set");
                }
            }
        };

        // Test warehouse
        if let Some((scheme, bucket, root)) = info {
            match scheme.as_str() {
                "s3" | "s3a" => {
                    let mut builder = S3::default();
                    if let Some(region) = &common.s3_region {
                        builder = builder.region(region);
                    }
                    if let Some(endpoint) = &common.s3_endpoint {
                        builder = builder.endpoint(endpoint);
                    }
                    if let Some(access_key) = &common.s3_access_key {
                        builder = builder.access_key_id(access_key);
                    }

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Add the `warehouse.path` option pointing at the table storage location, e.g. `s3://bucket/path` or `gs://bucket/path`.
  2. Alternatively, use a REST catalog (`catalog.type='rest'`) so the warehouse can be omitted or resolved by the server.
  3. Verify the option key spelling is exactly `warehouse.path`.

Example fix

// before
WITH (connector='iceberg', catalog.type='jdbc', catalog.uri='jdbc:mysql://...')
// after
WITH (connector='iceberg', catalog.type='jdbc', catalog.uri='jdbc:mysql://...', warehouse.path='s3://my-bucket/warehouse')
Defensive patterns

Strategy: validation

Validate before calling

if warehouse_path.is_none() && catalog_type != Some("rest") {
    return Err("warehouse.path is required unless catalog.type='rest'");
}

Try / catch

if let Err(e) = conn.validate_connection().await {
    if e.to_string().contains("`warehouse.path` must be set") {
        return Err(UserError::MissingOption("warehouse.path"));
    }
    return Err(e.into());
}

Prevention

When it happens

Trigger: Calling validate_connection (during CREATE CONNECTION/SOURCE/SINK validation) on an Iceberg connection where `warehouse.path` is unset and `catalog.type` resolves to something other than REST.

Common situations: Forgetting `warehouse.path` in the Iceberg connection options; assuming a JDBC or Hive catalog can infer the warehouse; copying a REST-catalog example config (which omits warehouse.path) while switching to a non-REST catalog.

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

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