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

failed to read SNAP file {path:?}: {e}

Error message

failed to read SNAP file {path:?}: {e}

What it means

When publish_module is given a --formats path, load_formats_from_snap reads the file (an insta-style .snap snapshot containing a YAML-encoded Formats value) with fs::read_to_string. This error wraps any read failure with the SNAP path; because read_to_string is used, it also fires for non-UTF-8 bytes (InvalidData). It runs after both bytecode files have loaded successfully.

Source

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

                    .map_err(|error| Error::VerifyDataBlob(Box::new(error)))
            }
        })
        .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> {

View on GitHub (pinned to 6c226ddcb3)

Solutions

  1. Check the path exists and is a regular file (`ls -l`); if the snapshot was never generated, run the app's test suite (e.g. `cargo test` in the application crate) to produce tests/snapshots/*.snap, or copy the .snap from the repo/artifacts that are supposed to contain it.
  2. Match the exact snapshot filename (e.g. format__format.yaml.snap vs format_wrapped_fungible__format_wrapped_fungible.yaml.snap) — use tab-completion or `ls tests/snapshots/` rather than typing it.
  3. If reading a file you edited, ensure it is saved as UTF-8 text without a BOM/binary prefix; fix permissions or mounts if the runtime environment differs from where the file lives.

Example fix

# before
linera publish-module ... --formats ./formats.yaml.snap   # file does not exist here

# after: generate or locate the real snapshot, then pass its path
ls examples/fungible/tests/snapshots/   # e.g. format__format.yaml.snap
linera publish-module ... --formats examples/fungible/tests/snapshots/format__format.yaml.snap
Defensive patterns

Strategy: try-catch

Validate before calling

let meta = std::fs::metadata(snap_path)
    .with_context(|| format!("SNAP {snap_path:?} missing; run the app's tests to generate it"))?;
anyhow::ensure!(meta.is_file(), "SNAP {snap_path:?} must be a regular UTF-8 text file");

Try / catch

let formats = match load_formats_from_snap(snap_path) {
    Ok(f) => f,
    Err(e) if e.to_string().contains("failed to read SNAP file") => {
        anyhow::bail!("cannot read {snap_path:?}: regenerate via `cargo test` or fix the path")
    }
    Err(e) => return Err(e.into()),
};

Prevention

When it happens

Trigger: Calling `linera publish-module ... --formats <path>` where the path is missing, is a directory, lacks read permission, or contains non-UTF-8 content. Typical trigger: passing a path to a .snap snapshot that lives in the application repo's tests/snapshots/ but running the CLI from a checkout that lacks it (or a typo'd filename).

Common situations: The .snap file is generated by running the application's test suite (insta snapshots like tests/snapshots/format__format.yaml.snap) and the developer never ran those tests or ran them in a different workspace; CI clones without test artifacts; the file was generated on another branch/version with a different snapshot name; binary or editor-mangled content breaks UTF-8 decoding.

Related errors

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