What causes "Index unknown '{index_key}' on insert" in nautechsystems/nautilus_trader?

Print the index_key value at the call site and compare it against the INDEX_* constants in cache.rs.

Index unknown '{index_key}' on insert

Error message

Index unknown '{index_key}' on insert

What it means

insert_index matches the index key against the known index constants (INDEX_ORDER_POSITION, INDEX_ORDER_CLIENT, etc.). If the index_key does not match any supported index, the match falls to the wildcard arm and bails with this error. It is an exhaustiveness guard over the set of index types the Redis cache knows how to write.

Source

Thrown at crates/infrastructure/src/redis/cache.rs:996

            Ok(())
        }
        INDEX_ORDER_CLIENT => {
            if !value.len().is_multiple_of(2) {
                anyhow::bail!(
                    "Invalid hash index payload for '{index_key}': expected field-value pairs"
                );
            }

            let entries = value
                .as_chunks::<2>()
                .0
                .iter()
                .map(|entry| (entry[0].as_ref(), entry[1].as_ref()))
                .collect::<Vec<(&[u8], &[u8])>>();
            pipe.hset_multiple(key, &entries);
            Ok(())
        }
        _ => anyhow::bail!("Index unknown '{index_key}' on insert"),
    }
}

fn insert_string(pipe: &mut Pipeline, key: &str, value: &[u8]) {
    pipe.set(key, value);
}

fn insert_set(pipe: &mut Pipeline, key: &str, value: &[u8]) {
    pipe.sadd(key, value);
}

fn insert_hset(pipe: &mut Pipeline, key: &str, name: &[u8], value: &[u8]) {
    pipe.hset(key, name, value);
}

fn insert_list(pipe: &mut Pipeline, key: &str, value: &[u8]) {
    pipe.rpush(key, value);
}

View on GitHub (pinned to 18893faf8b)

Solutions

Print the index_key value at the call site and compare it against the INDEX_* constants in cache.rs.
Correct the index key typo to a supported constant (INDEX_ORDER_POSITION or INDEX_ORDER_CLIENT).
If a new index type is legitimately needed, add a match arm in insert_index implementing the write (e.g. via insert_hset or hset_multiple).
Align crate versions so core and the redis adapter agree on the index constants.

Example fix

// before
insert(pipe, "order:my_custom_idx", key, value)?; // unknown index
// after
insert(pipe, INDEX_ORDER_CLIENT, key, value)?; // supported index

Defensive patterns

Strategy: validation

Validate before calling

// Only pass the constants themselves, never constructed strings
const SUPPORTED: [&str; 2] = [INDEX_ORDER_POSITION, INDEX_ORDER_CLIENT];
assert!(SUPPORTED.contains(&index_key), "unsupported index: {index_key}");

Try / catch

// Python
try:
    cache.insert(index_key, key, value)
except RuntimeError as e:
    if "Index unknown" in str(e):
        log.warning("Skipping unknown index %s", index_key)
    else:
        raise

Prevention

Reference the INDEX_* constants directly instead of hand-writing index key strings.
Keep core and redis-adapter crate versions in sync.
Add a match-arm test covering every index constant used in your deployment.

When it happens

Trigger: Calling insert_index (via insert) with an index_key string that is not one of the defined INDEX_* constants — e.g. a typo'd index name, a custom index introduced upstream but not yet supported by this adapter, or an index constant renamed.

Common situations: Version mismatch where a newer NautilusTrader core emits an index the installed redis cache crate version does not know; copy-paste typo in index key; a fork adding custom indexes without extending insert_index.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/ddabe8f5e3858013. Report an issue: GitHub.