What causes "Invalid order key item `{item}`" in risingwavelabs/risingwave?

Replace the blank item with a real column name from the table

Invalid order key item `{item}`

Error message

Invalid order key item `{item}`

What it means

After trimming, an order key item must contain at least one whitespace-separated token (the column name). If split_whitespace yields nothing, the item consists only of whitespace (e.g. a comma followed by spaces). The error names the offending item so the developer can locate it in the order_key string.

Source

Thrown at src/connector/src/sink/iceberg/create_table.rs:492

    }
    Ok(partition_columns)
}

pub fn parse_order_key_exprs(
    expr: String,
) -> std::result::Result<Vec<IcebergOrderKeyField>, anyhow::Error> {
    let mut order_keys = Vec::new();
    let mut seen_columns = std::collections::HashSet::new();

    for raw_item in expr.split(',') {
        let item = raw_item.trim();
        if item.is_empty() {
            bail!("Invalid order key: empty item in `{expr}`");
        }

        let tokens = item.split_whitespace().collect_vec();
        if tokens.is_empty() {
            bail!("Invalid order key item `{item}`");
        }
        if tokens.len() > 4 {
            bail!(
                "Invalid order key item `{item}`\nHINT: Supported format is `column [asc|desc] [nulls first|last]`"
            );
        }

        let column = tokens[0];
        if !ORDER_KEY_COLUMN_RE.is_match(column) {
            bail!(
                "Invalid order key column `{column}`\nHINT: Only plain column names are supported in order_key"
            );
        }
        if !seen_columns.insert(column.to_ascii_lowercase()) {
            bail!("Duplicate column `{column}` in order_key");
        }

        let mut direction = SortDirection::Ascending;

View on GitHub (pinned to 6469eb736d)

Solutions

Replace the blank item with a real column name from the table
Remove the extra comma producing the blank item
Recount the items: order_key='a,b,c' must yield exactly the columns you intend
Quote the order_key value carefully so shell/SQL quoting does not eat a name

Example fix

// before
order_key = 'user_id, , created_at'
// after
order_key = 'user_id, created_at'

Defensive patterns

Strategy: validation

Validate before calling

for item in expr.split(',').map(|s| s.trim()) {
    if item.split_whitespace().count() == 0 {
        return Err(format!("order_key item `{item}` has no tokens; supply a column name"));
    }
}

Type guard

fn order_key_item_is_blank(item: &str) -> bool {
    !item.trim().is_empty() && item.split_whitespace().next().is_none()
}

Prevention

Always place a real column name between commas in order_key
After editing configs, re-read the rendered order_key string, not the template
Avoid whitespace placeholders; delete an item entirely if it is not needed
Test the option parser with a unit test covering blank items

When it happens

Trigger: An order_key item that trims to non-empty but contains only spaces between commas, e.g. order_key='id, ,name' — the middle item ` ` is not empty after trim? (trim removes spaces, so this hits 590); actually this branch is reachable for items of whitespace when split(',') boundaries differ, e.g. order_key='id , ' style strings in edge cases. Practically: any item with no token after tokenization.

Common situations: Whitespace-only placeholder left where a column name should be; template expansion producing blank items; mis-edited config where a column name was deleted but the comma kept.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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