cross-rs/cross · info

should contain at least one

Error message

should contain at least one

What it means

`Image::to_definite_with` (src/docker/image.rs:48) picks the image platform from `self.toolchain`. When the toolchain list has exactly one entry, it takes it with `first().expect("should contain at least one")`. The expect encodes the invariant that a len==1 slice always has a first element; it is a defensive assertion, not a user-facing validation, and is unreachable while the length check is present.

Solutions

  1. Treat as an internal invariant; report as a bug if it ever triggers
  2. If refactoring, replace the len+expect pattern with `if let [platform] = self.toolchain.as_slice()` or `only = self.toolchain.first()?` with explicit error handling
  3. If you hit platform-selection issues, inspect the toolchain image list rather than this expect

Example fix

// before
let platform = if self.toolchain.len() == 1 {
    self.toolchain.first().expect("should contain at least one")
} else { ... };
// after
let platform = match self.toolchain.as_slice() {
    [only] => only,
    _ => /* multi-platform arch filtering */ ...,
};
Defensive patterns

Strategy: validation

Validate before calling

// inspect resolved toolchain images before definite-image resolution
assert!(!image.toolchain.is_empty(), "toolchain image list must be non-empty");

Type guard

fn single<T>(v: &[T]) -> Option<&T> { if v.len() == 1 { v.first() } else { None } }

Prevention

When it happens

Trigger: Only fires if the `self.toolchain.len() == 1` guard is removed/changed or the collection mutates between the check and `first()`. Normal execution: single-toolchain image resolution takes this branch; multi-toolchain images go through the same_arch filtering path.

Common situations: Users never see this panic directly; it appears during maintenance/refactoring. Confusion arises when image platform selection behaves unexpectedly — that is governed by the len check and the arch-filtering branch, not the expect.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/f796aad19c7c0b63. Report an issue: GitHub.

Appendix: source

Thrown at src/docker/image.rs:48

    pub reference: ImageReference,
    // The toolchain triple the image is built for
    pub toolchain: Vec<ImagePlatform>,
}

impl PossibleImage {
    pub fn to_definite_with(&self, engine: &Engine, msg_info: &mut MessageInfo) -> Result<Image> {
        let ImageReference::Name(name) = self.reference.clone() else {
            eyre::bail!("cannot make definite Image from unqualified PossibleImage");
        };

        if self.toolchain.is_empty() {
            Ok(Image {
                name,
                platform: ImagePlatform::DEFAULT,
            })
        } else {
            let platform = if self.toolchain.len() == 1 {
                self.toolchain.first().expect("should contain at least one")
            } else {
                let same_arch = self
                    .toolchain
                    .iter()
                    .filter(|platform| {
                        &platform.architecture
                            == engine.arch.as_ref().unwrap_or(&Architecture::Amd64)
                    })
                    .collect::<Vec<_>>();

                if same_arch.len() == 1 {
                    // pick the platform with the same architecture
                    same_arch.first().expect("should contain one element")
                } else if let Some(platform) = same_arch
                    .iter()
                    .find(|platform| &platform.os == engine.os.as_ref().unwrap_or(&Os::Linux))
                {
                    *platform

View on GitHub (pinned to 8c1a8aa4b6)