influxdata/influxdb · error · Error

specified key column

Error message

specified key column (name: {column_name}) does not exist in the table schema

What it means

This is the `KeyColumnDoesNotExistByName` variant of the last-cache `Error` enum. It is raised when a column given by name as a key column for a last-of-value cache does not exist in the table's schema. The cache validates every named key column against the table definition at cache-creation time and rejects unknown names.

Solutions

  1. List the table's actual columns and correct the key column name spelling/case
  2. Remove the invalid name from the `key_columns` list, or create the column first
  3. Align cache configs with the schema after any column renames

Example fix

// before
create_last_cache(db, "sensors", "latest", Some(&["lokation"]), None, 10, None);
// after
create_last_cache(db, "sensors", "latest", Some(&["location"]), None, 10, None);
Defensive patterns

Strategy: validation

Validate before calling

fn valid_key_names(schema: &Schema, names: &[&str]) -> Result<(), String> {
    names.iter()
        .find(|n| schema.field_name_to_id(n).is_err())
        .map_or(Ok(()), |n| Err(format!("key column '{n}' not found")))
}

Type guard

fn key_column_named(schema: &Schema, name: &str) -> Option<ColumnId> {
    schema.field_name_to_id(name).ok()
}

Try / catch

match res {
    Err(LastCacheError::KeyColumnDoesNotExistByName { column_name }) => {
        eprintln!("unknown key column '{column_name}'; check spelling against table schema");
    }
    Err(e) => return Err(e.into()),
    Ok(_) => {}
}

Prevention

When it happens

Trigger: Calling `create_last_cache` with `key_columns` containing a misspelled or non-existent column name; naming a field that exists in another table but not the target table; referencing a tag/field removed by a schema change.

Common situations: Typos or case mismatches in column names in cache configuration; renaming a tag column without updating last-cache configs; copying cache definitions between tables with different schemas.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/9b7be6271e3ef861. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_cache/src/last_cache/mod.rs:28

mod table_function;
use schema::InfluxColumnType;
pub use table_function::{LAST_CACHE_UDTF_NAME, LastCacheFunction};

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("invalid cache size")]
    InvalidCacheSize,
    #[error(
        "last cache already exists for database and table, but it was configured differently: {reason}"
    )]
    CacheAlreadyExists { reason: String },
    #[error("specified column (name: {column_name}) does not exist in the table definition")]
    ColumnDoesNotExistByName { column_name: String },
    #[error("specified column (id: {column_id}) does not exist in the table definition")]
    ColumnDoesNotExistById { column_id: ColumnId },
    #[error("specified key column (id: {column_id}) does not exist in the table schema")]
    KeyColumnDoesNotExist { column_id: ColumnId },
    #[error("specified key column (name: {column_name}) does not exist in the table schema")]
    KeyColumnDoesNotExistByName { column_name: String },
    #[error("key column must be string, int, uint, or bool types, got: {column_type}")]
    InvalidKeyColumn { column_type: InfluxColumnType },
    #[error("specified value column ({column_id}) does not exist in the table schema")]
    ValueColumnDoesNotExist { column_id: ColumnId },
    #[error("requested last cache does not exist")]
    CacheDoesNotExist,
}

impl Error {
    fn cache_already_exists(reason: impl Into<String>) -> Self {
        Self::CacheAlreadyExists {
            reason: reason.into(),
        }
    }
}

#[cfg(test)]

View on GitHub (pinned to 06200ef96b)