linera-io/linera-protocol · error · std::io::Error

SNAP file {path:?} is missing the `---` frontmatter delimite

Error message

SNAP file {path:?} is missing the `---` frontmatter delimiters

What it means

load_formats_from_snap expects the insta snapshot layout: a file starting with a `---` header line, a metadata block, a closing `---` line, then the YAML body with the Formats value (strip_snap_frontmatter at client_context.rs:980 requires a leading "---\n" and a "\n---\n" terminator). If either delimiter is absent the function returns InvalidData with this message — the file was read fine but is not in snapshot format.

Source

Thrown at linera-client/src/client_context.rs:965

        .await?;

        info!("{}", "Data blob verified successfully!");
        Ok(())
    }
}

/// Reads an insta SNAP file containing a YAML-encoded `Formats` value and parses
/// it. The caller BCS-serializes the result to obtain the application formats
/// blob payload: BCS matches the documented intent (the blob is "the BCS
/// serialization of an application's `Formats`") and the encoding the explorer
/// decodes with.
#[cfg(feature = "fs")]
fn load_formats_from_snap(path: &std::path::Path) -> Result<linera_sdk::formats::Formats, Error> {
    let content = fs::read_to_string(path).map_err(|e| {
        std::io::Error::new(e.kind(), format!("failed to read SNAP file {path:?}: {e}"))
    })?;
    let body = strip_snap_frontmatter(&content).ok_or_else(|| {
        std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("SNAP file {path:?} is missing the `---` frontmatter delimiters"),
        )
    })?;
    let formats = serde_yaml_08::from_str(body).map_err(|e| {
        std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("failed to parse SNAP body in {path:?} as Formats: {e}"),
        )
    })?;
    Ok(formats)
}

#[cfg(feature = "fs")]
fn strip_snap_frontmatter(content: &str) -> Option<&str> {
    let rest = content.strip_prefix("---\n")?;
    let end = rest.find("\n---\n")?;
    Some(&rest[end + "\n---\n".len()..])

View on GitHub (pinned to 6c226ddcb3)

Solutions

  1. Open the file and confirm line 1 is exactly `---` and that a later line is exactly `---` followed by a newline, with the Formats YAML after it — easiest check: compare against a known-good snapshot from tests/snapshots/ in the same repo.
  2. Regenerate the file via the intended path (run the app's tests so insta writes the .snap, or copy a working .snap) rather than authoring it by hand.
  3. If hand-authoring, switch line endings to LF and make sure no BOM precedes the first `---` and the closing `---` has content (the YAML body) after it.

Example fix

# before: plain YAML, no frontmatter -> this error
format:
  type: ... 

# after: insta snap layout (LF line endings, body after closing ---)
---
source: tests/format.rs
expression: format
---
type: ...
Defensive patterns

Strategy: validation

Validate before calling

fn snap_has_frontmatter(content: &str) -> bool {
    content.starts_with("---\n") && content[4..].contains("\n---\n")
}

// std::fs::read_to_string(path).map(|c| snap_has_frontmatter(&c))? before publishing

Type guard

fn snap_has_frontmatter(content: &str) -> bool {
    content.starts_with("---\n") && content[4..].contains("\n---\n")
}

Prevention

When it happens

Trigger: Passing --formats a plain YAML file with no frontmatter, a file whose first line is not exactly `---`, a file using `...` or ``` fences instead of `---`, or one where the closing delimiter is missing or written as the very first/last line without trailing newlines. Any of these makes strip_snap_frontmatter return None.

Common situations: Hand-writing a formats file instead of using the insta-generated tests/snapshots/*.snap; exporting YAML from another tool and renaming it .snap; an editor or formatter stripping the leading `---` or collapsing blank lines; Windows line endings making the "\n---\n" literal match fail; trimming trailing newlines so the closing delimiter is not followed by a newline.

Related errors

AI-assisted analysis of linera-io/linera-protocol@6c226ddcb3 (2026-08-22). Data as JSON: /api/errors/c0995592f6b05920. Report an issue: GitHub.