CROSS_RUNNER environment variable name is reserved and…

Error message

CROSS_RUNNER environment variable name is reserved and cannot be pass through

What it means

When parsing environment variables to pass into the container, cross rejects any variable named `CROSS_RUNNER` in the pass-through set (`-e`/`--env` style arguments). CROSS_RUNNER is reserved by cross itself for internal metadata, so the user is not allowed to set it through the passthrough mechanism.

Solutions

Remove CROSS_RUNNER from the variables being passed with --env / --env-file.
If a custom value is needed inside the container, rename it (e.g. MY_CROSS_RUNNER).
Filter CROSS_RUNNER out of bulk env forwarding in the CI script before invoking cross.

Example fix

// before
$ cross build --target aarch64-unknown-linux-gnu --env CROSS_RUNNER=custom
// after
$ cross build --target aarch64-unknown-linux-gnu --env MY_CROSS_RUNNER=custom

Defensive patterns

Strategy: validation

Validate before calling

const RESERVED = ['CROSS_RUNNER'];
function assertPassthroughEnv(vars) {
  for (const key of Object.keys(vars)) {
    if (RESERVED.includes(key)) {
      throw new Error(`${key} is reserved and cannot be passed through`);
    }
  }
}

Prevention

Filter out CROSS_RUNNER before bulk-forwarding env vars to cross.
Prefix custom runner-related vars with your own namespace (MY_APP_...).
Document reserved variable names in CI configuration.

When it happens

Trigger: Invoking cross with `--env CROSS_RUNNER=...` (or `--env-file` containing it) so that the key/value pair validation in the env parser hits the `if key == "CROSS_RUNNER"` check.

Common situations: CI scripts that blanket-forward all host env vars to the container, accidentally including a CROSS_RUNNER value set elsewhere; users trying to influence the in-container cross runner.

Related errors

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

Appendix: source

Thrown at src/docker/shared.rs:903

    let (key, value) = match var.split_once('=') {
        Some((key, value)) => (key, Some(value)),
        _ => (var, None),
    };

    if value.is_none()
        && !*warned
        && !var
            .chars()
            .all(|c| matches!(c, 'a'..='z' | 'A'..='Z' | '_' | '0'..='9'))
    {
        msg_info.warn(format_args!(
            "got {var_type} of \"{var}\" which is not a valid environment variable name. the proper syntax is {var_syntax}"
        ))?;
        *warned = true;
    }

    if key == "CROSS_RUNNER" {
        eyre::bail!(
            "CROSS_RUNNER environment variable name is reserved and cannot be pass through"
        );
    }

    Ok((key, value))
}

impl CommandVariant {
    pub(crate) fn safe_command(&self) -> SafeCommand {
        SafeCommand::new(self.to_str())
    }
}

pub(crate) trait DockerCommandExt {
    fn add_configuration_envvars(&mut self);
    fn add_envvars(
        &mut self,
        options: &DockerOptions,

View on GitHub (pinned to 8c1a8aa4b6)