nautechsystems/nautilus_trader · critical

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

Error message

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

What it means

order_side_from_cstr converts a C string into an OrderSideOptional enum via FromStr. Unrecognized strings panic with this message; abort_on_panic turns the panic into a process abort at the FFI boundary. OrderSideOptional includes a NO_ORDER_SIDE/none-style variant, so callers should use that rather than an empty or ad-hoc string.

Source

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

pub extern "C" fn order_side_to_cstr(value: OrderSideOptional) -> *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 `OrderSideOptional` variant.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn order_side_from_cstr(ptr: *const c_char) -> OrderSideOptional {
    abort_on_panic(|| {
        let value = unsafe { cstr_as_str(ptr) };
        OrderSideOptional::from_str(value).unwrap_or_else(|_| {
            panic!("invalid `OrderSideOptional` enum string value, was '{value}'")
        })
    })
}

#[unsafe(no_mangle)]
pub extern "C" fn order_status_to_cstr(value: OrderStatus) -> *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 `OrderStatus` variant.

View on GitHub (pinned to 18893faf8b)

Solutions

1. Pass the exact OrderSideOptional variant string (e.g. 'BUY', 'SELL', or the none-variant string) per the enum's FromStr definition.
2. For missing/neutral sides, explicitly pass the none-variant string instead of an empty string.
3. Map feed-specific side codes ('B'/'S') to canonical variants in the caller.
4. Validate the string against the variant whitelist before calling.
5. Rebuild against the matching crate version if variant names changed.

Example fix

// before
order_side_from_cstr(""); // panics: empty string

// after
order_side_from_cstr("NO_ORDER_SIDE"); // explicit none-variant string

const ORDER_SIDE_OPTIONAL_VARIANTS = new Set(["BUY", "SELL", "NO_ORDER_SIDE"]);
function toOrderSideOptional(raw) {
  const v = raw == null || raw === "" ? "NO_ORDER_SIDE" : raw;
  if (!ORDER_SIDE_OPTIONAL_VARIANTS.has(v)) throw new Error(`unsupported OrderSideOptional: ${raw}`);
  return v;
}

function isOrderSideOptional(v) { return v === 'BUY' || v === 'SELL' || v === 'NO_ORDER_SIDE'; }

Not applicable: panics abort the process at the FFI boundary and cannot be caught. Convert null/empty to the explicit none-variant string beforehand.

When it happens

Trigger: Calling order_side_from_cstr(ptr) with strings like 'BUY_ORDER', 'Long', 'flat', '0', or an empty string that do not match any OrderSideOptional variant. Only exact variant strings accepted by FromStr parse; empty input will NOT map to the none variant.

Common situations: Mapping broker-side side vocabulary ('B'/'S', 'long'/'short') directly into the FFI call; passing None/empty where the 'NO_ORDER_SIDE' variant string is required; case mismatches; version drift after a rename.

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 `InstrumentClass` enum string value, was '{value}'
• invalid `BarAggregation` enum string value, was '{value}'
• invalid `BookAction` enum string value, was '{value}'

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