nautechsystems/nautilus_trader · error

unsupported cache snapshot blob_ref {blob_ref}

Error message

unsupported cache snapshot blob_ref {blob_ref}

What it means

parse_position_snapshot_blob_ref parses blob references of the exact form 'cache://position-snapshots/<position_id>/<frame_index>'. This error is raised when the string does not start with the required 'cache://position-snapshots/' prefix, meaning the blob_ref is not a position-snapshot reference the cache can resolve.

Source

Thrown at crates/common/src/cache/position.rs:446

    /// Gets position snapshot IDs for the `instrument_id`.
    #[must_use]
    pub fn position_snapshot_ids(&self, instrument_id: &InstrumentId) -> AHashSet<PositionId> {
        self.position_snapshots
            .keys()
            .filter(|position_id| {
                self.positions
                    .get(position_id)
                    .is_some_and(|position| position.borrow().instrument_id == *instrument_id)
            })
            .copied()
            .collect()
    }
}

fn parse_position_snapshot_blob_ref(blob_ref: &str) -> anyhow::Result<(PositionId, usize)> {
    let Some(rest) = blob_ref.strip_prefix("cache://position-snapshots/") else {
        anyhow::bail!("unsupported cache snapshot blob_ref {blob_ref}");
    };

    let Some((position_id, snapshot_index)) = rest.rsplit_once('/') else {
        anyhow::bail!("malformed position snapshot blob_ref {blob_ref}");
    };

    if position_id.is_empty() {
        anyhow::bail!("position snapshot blob_ref {blob_ref} has empty position id");
    }

    let snapshot_index = snapshot_index.parse::<usize>().map_err(|e| {
        anyhow::anyhow!("position snapshot blob_ref {blob_ref} has invalid frame index: {e}")
    })?;

    Ok((PositionId::new(position_id), snapshot_index))
}

fn decode_position_snapshot_blob(

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure the blob_ref starts exactly with 'cache://position-snapshots/'
2. Only pass blob_refs that were produced by the position snapshot writer (position_snapshot_frame), don't hand-craft them
3. Check for truncation or string corruption when persisting/transporting blob_refs

Example fix

// before
let blob_ref = format!("cache://positions/{position_id}/{index}");
// after
let blob_ref = format!("cache://position-snapshots/{position_id}/{index}");

fn is_position_snapshot_ref(blob_ref: &str) -> bool {
    blob_ref.starts_with("cache://position-snapshots/")
}
assert!(is_position_snapshot_ref(&blob_ref), "bad blob_ref: {blob_ref}");

fn as_position_snapshot_ref(blob_ref: &str) -> Option<&str> {
    blob_ref.strip_prefix("cache://position-snapshots/")
}

match cache.restore_snapshot_blob(blob_ref, blob) {
    Ok(p) => /* use p */,
    Err(e) if e.to_string().contains("unsupported cache snapshot blob_ref") => /* fix ref scheme */,
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling position_snapshot_frame or restore_snapshot_blob with a blob_ref that has a different scheme/path (e.g. 'cache://orders/...', a bare ID, a different cache collection name, or a truncated/corrupted string).

Common situations: Storing blob_refs from one cache collection and replaying them against the position snapshot API; hand-building blob_ref strings with a typo in the prefix; loading refs written by another library version that used a different path scheme.

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

• malformed position snapshot blob_ref {blob_ref}
• position snapshot blob_ref {blob_ref} has empty position id
• DataActor {} must be registered before calling `cache()` - t
• Order {client_order_id} not found
• Position {position_id} not found

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