nautechsystems/nautilus_trader · error

Invalid UUID4 string

Error message

Invalid UUID4 string

What it means

The `From<&str> for UUID4` impl parses the string with `from_str` and `.expect`s success, so any input that is not a valid UUID v4 string panics. The library intentionally treats a malformed UUID string as unrecoverable programmer error rather than a fallible parse.

Source

Thrown at crates/core/src/uuid.rs:200

    type Err = String;

    /// Attempts to create a [`UUID4`] from a string representation.
    ///
    /// The string should be a valid UUID in the standard format (e.g., "2d89666b-1a1e-4a75-b193-4eb3b454c757").
    ///
    /// # Errors
    ///
    /// Returns an error if the `value` is not a valid UUID version 4 RFC 4122.
    fn from_str(value: &str) -> Result<Self, Self::Err> {
        let uuid = Uuid::try_parse(value).map_err(|e| e.to_string())?;
        Self::try_validate_v4(&uuid)?;
        Ok(Self::from_validated_uuid(&uuid))
    }
}

impl From<&str> for UUID4 {
    fn from(value: &str) -> Self {
        Self::from_str(value).expect("Invalid UUID4 string")
    }
}

impl From<String> for UUID4 {
    fn from(value: String) -> Self {
        Self::from_str(&value).expect("Invalid UUID4 string")
    }
}

impl From<uuid::Uuid> for UUID4 {
    /// Creates a [`UUID4`] from a [`uuid::Uuid`].
    ///
    /// # Panics
    ///
    /// Panics if the `value` is not a valid UUID version 4 RFC 4122.
    fn from(value: uuid::Uuid) -> Self {
        Self::validate_v4(&value);
        Self::from_validated_uuid(&value)

View on GitHub (pinned to 18893faf8b)

Solutions

1. Use the fallible API `UUID4::from_str(value)` and handle the `Result` instead of `From::from`
2. Validate the string with the uuid crate (`uuid::Uuid::parse_str` and check version 4) before converting
3. Fix the data source so it emits canonical lowercase hyphenated UUID4 strings
4. If the value is an external identifier, model it as its own type (e.g. ClientOrderId) rather than forcing it into UUID4

Example fix

// before
let id = UUID4::from(config_value); // panics if malformed
// after
let id = UUID4::from_str(config_value)
    .unwrap_or_else(|e| panic!("invalid UUID4 in config: {e}"));
// or generate when absent
let id = config_value.map(UUID4::from_str).unwrap_or_else(|| Ok(UUID4::new()))?;

// Rust
fn is_uuid4(s: &str) -> bool {
    uuid::Uuid::parse_str(s).map(|u| u.get_version_num() == 4).unwrap_or(false)
}

fn try_uuid4(s: &str) -> Option<UUID4> { UUID4::from_str(s).ok() }

// Use the fallible API instead of From
match UUID4::from_str(raw) {
    Ok(id) => id,
    Err(e) => { log::error!("bad UUID4 '{raw}': {e}"); return Err(e.into()); }
}

When it happens

Trigger: Calling `UUID4::from(some_str)` where `some_str` is not exactly a 36-char hyphenated UUID4 (e.g. `'abc'`, an empty string, a UUID without hyphens, or a non-v4 UUID variant/version).

Common situations: Passing user- or config-supplied IDs (order client IDs, external trade IDs) where a UUID4 is expected; reading truncated IDs from logs or CSV; storing UUIDs in a format that strips hyphens or uppercases braces.

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

• Invalid scientific notation exponent '{exponent}': must be a
• {FAILED}: {e}
• {FAILED}: {e}
• C string contains invalid JSON
• C string JSON must be an array of strings

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