risingwavelabs/risingwave · error

pgvector dimension out of range in type `{}`: expect 1..={}

Error message

pgvector dimension out of range in type `{}`: expect 1..={}

What it means

After parsing the pgvector dimension, `parse_pgvector_dimension` range-checks it against RisingWave's vector size limit (`DataType::VEC_MAX_SIZE`). Dimensions below 1 or above the max bail with 'pgvector dimension out of range'.

Source

Thrown at src/connector/src/connector_common/postgres.rs:760

fn parse_pgvector_dimension(type_name: &str) -> ConnectorResult<Option<usize>> {
    let normalized = type_name.trim().to_ascii_lowercase();
    if normalized == "vector" {
        bail!("pgvector type `vector` is missing dimension, expected `vector(n)`")
    }
    if !normalized.starts_with("vector(") || !normalized.ends_with(')') {
        return Ok(None);
    }

    let dim_text = normalized
        .trim_start_matches("vector(")
        .trim_end_matches(')')
        .trim();
    let dim = dim_text
        .parse::<usize>()
        .map_err(|_| anyhow!("invalid pgvector dimension in type `{type_name}`"))?;

    if !(1..=DataType::VEC_MAX_SIZE).contains(&dim) {
        bail!(
            "pgvector dimension out of range in type `{}`: expect 1..={}",
            type_name,
            DataType::VEC_MAX_SIZE
        );
    }

    Ok(Some(dim))
}

// Used for sink connector
// We use `sea-schema` for table schema discovery.
// So we have to map `sea-schema` pg types
// to `tokio-postgres` pg types (which we use for query binding).
fn sea_type_to_pg_type(sea_type: &SeaType) -> ConnectorResult<tokio_postgres::types::Type> {
    use tokio_postgres::types::Type as PgType;
    match sea_type {
        SeaType::SmallInt => Ok(PgType::INT2),
        SeaType::Integer => Ok(PgType::INT4),

View on GitHub (pinned to 6469eb736d)

Solutions

1. Reduce the upstream column dimension to a supported value (1..=VEC_MAX_SIZE, e.g. 1536 or 4096)
2. Check RisingWave's current max vector dimension in `DataType::VEC_MAX_SIZE` and size the embedding model output accordingly
3. Split or truncate embeddings upstream before storing them in a monitored column

Example fix

-- before
CREATE TABLE t (v vector(16000));
-- after
CREATE TABLE t (v vector(1536));

fn check_vector_dim(dim: usize, max: usize) -> Result<(), String> {
    if (1..=max).contains(&dim) { Ok(()) } else { Err(format!("dim {dim} outside 1..={max}")) }
}
// call with max = DataType::VEC_MAX_SIZE before setup

fn dim_in_range(type_name: &str, max: usize) -> bool {
    let inner = type_name.trim().to_ascii_lowercase();
    inner.starts_with("vector(") && inner.ends_with(')')
        && inner["vector(".len()..inner.len()-1].trim().parse::<usize>()
            .map(|d| (1..=max).contains(&d)).unwrap_or(false)
}

match setup_result {
    Err(e) if e.to_string().contains("dimension out of range") => {
        Err(CdcError::PgVectorDimTooLarge(e))
    }
    other => other,
}

When it happens

Trigger: `parse_pgvector_dimension` seeing `vector(n)` where n = 0 or n > `DataType::VEC_MAX_SIZE` (RisingWave's maximum vector dimension).

Common situations: Upstream pgvector columns with very large dimensions (e.g. `vector(20000)`) that exceed RisingWave's limit; accidentally declared zero-dimension vectors.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• pgvector type `vector` is missing dimension, expected `vecto
• invalid pgvector dimension in type `{type_name}`
• PostgreSQL snapshot column `{name}` vector dimension mismatc
• Invalid value for Ratio strategy: must be between 0.0 and 1.
• Invalid date: days: {days}

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