nautechsystems/nautilus_trader · critical

invalid `InstrumentClass` enum string value, was '{value}'

Error message

invalid `InstrumentClass` enum string value, was '{value}'

What it means

`instrument_class_from_cstr` converts a C string into the Rust `InstrumentClass` enum and panics when the string matches no variant. The library cannot represent an unknown instrument class, so it panics — and because this is an FFI boundary, `abort_on_panic` turns the panic into a process abort. Accepted strings are exactly the `InstrumentClass` serializations produced by `instrument_class_to_cstr`.

Source

Thrown at crates/model/src/ffi/enums.rs:388

pub extern "C" fn instrument_class_to_cstr(value: InstrumentClass) -> *const c_char {
    str_to_cstr(value.as_ref())
}

/// Returns an enum from a C string.
///
/// # Safety
///
/// Assumes `ptr` is a valid C string pointer.
///
/// # Panics
///
/// Panics if the C string does not correspond to a valid `InstrumentClass` variant.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn instrument_class_from_cstr(ptr: *const c_char) -> InstrumentClass {
    abort_on_panic(|| {
        let value = unsafe { cstr_as_str(ptr) };
        InstrumentClass::from_str(value).unwrap_or_else(|_| {
            panic!("invalid `InstrumentClass` enum string value, was '{value}'")
        })
    })
}

#[unsafe(no_mangle)]
pub extern "C" fn bar_aggregation_to_cstr(value: BarAggregation) -> *const c_char {
    str_to_cstr(value.as_ref())
}

/// Returns an enum from a C string.
///
/// # Safety
///
/// Assumes `ptr` is a valid C string pointer.
///
/// # Panics
///
/// Panics if the C string does not correspond to a valid `BarAggregation` variant.

View on GitHub (pinned to 18893faf8b)

Solutions

1. Dump the exact string at the call site and diff it against the canonical `InstrumentClass` variant strings.
2. Use the library's `InstrumentClass` enum plus `instrument_class_to_cstr` to produce valid strings instead of hand-written ones.
3. Confirm you are using the right enum — `InstrumentClass` (instrument kinds like SPOT/FUTURE) differs from `AssetClass`.
4. Whitelist/map external catalog class names to `InstrumentClass` before calling the FFI.
5. Normalize case/whitespace; the FromStr match is exact, and failure aborts the process.

Example fix

// before
cls = "PERPETUAL"
instrument_class_from_cstr(cls.encode())
// after
cls = "PERP"  # canonical InstrumentClass variant string (verify in enum definition)
instrument_class_from_cstr(cls.encode())

VALID_INSTRUMENT_CLASSES = {"SPOT", "FUTURE", "OPTION"}  # from InstrumentClass definition
assert class_str in VALID_INSTRUMENT_CLASSES, f"bad InstrumentClass: {class_str!r}"
instrument_class_from_cstr(class_str.encode())

def is_valid_instrument_class(s: str) -> bool:
    return s in VALID_INSTRUMENT_CLASSES  # canonical strings from InstrumentClass::as_ref

When it happens

Trigger: Calling `instrument_class_from_cstr(ptr)` with a non-canonical instrument-class string (e.g. 'perpetual' instead of the canonical variant spelling), an empty string, or a value whose spelling differs from the current enum definition.

Common situations: Loading instruments from external catalogs with their own class vocabulary; typos in config; passing an older library's serialization after an upgrade; confusing `AssetClass` with `InstrumentClass` — they are different enums with different vocabularies.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid `AggressorSide` enum string value, was '{value}'
• invalid `AssetClass` enum string value, was '{value}'
• invalid `BarAggregation` enum string value, was '{value}'
• invalid `BookAction` enum string value, was '{value}'
• invalid `BookType` enum string value, was '{value}'

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