{"record":{"id":"049be1002c0c89ee","repo":"cross-rs/cross","slug":"cross-runner-environment-variable-name-is-reserved-and","errorCode":null,"errorMessage":"CROSS_RUNNER environment variable name is reserved and cannot be pass through","messagePattern":"CROSS_RUNNER environment variable name is reserved and cannot be pass through","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/docker/shared.rs","lineNumber":903,"sourceCode":"    let (key, value) = match var.split_once('=') {\n        Some((key, value)) => (key, Some(value)),\n        _ => (var, None),\n    };\n\n    if value.is_none()\n        && !*warned\n        && !var\n            .chars()\n            .all(|c| matches!(c, 'a'..='z' | 'A'..='Z' | '_' | '0'..='9'))\n    {\n        msg_info.warn(format_args!(\n            \"got {var_type} of \\\"{var}\\\" which is not a valid environment variable name. the proper syntax is {var_syntax}\"\n        ))?;\n        *warned = true;\n    }\n\n    if key == \"CROSS_RUNNER\" {\n        eyre::bail!(\n            \"CROSS_RUNNER environment variable name is reserved and cannot be pass through\"\n        );\n    }\n\n    Ok((key, value))\n}\n\nimpl CommandVariant {\n    pub(crate) fn safe_command(&self) -> SafeCommand {\n        SafeCommand::new(self.to_str())\n    }\n}\n\npub(crate) trait DockerCommandExt {\n    fn add_configuration_envvars(&mut self);\n    fn add_envvars(\n        &mut self,\n        options: &DockerOptions,","sourceCodeStart":885,"sourceCodeEnd":921,"githubUrl":"https://github.com/cross-rs/cross/blob/8c1a8aa4b661711f4b7b6ac07c2e8929ce2f7d27/src/docker/shared.rs#L885-L921","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n$ cross build --target aarch64-unknown-linux-gnu --env CROSS_RUNNER=custom\n// after\n$ cross build --target aarch64-unknown-linux-gnu --env MY_CROSS_RUNNER=custom","handlingStrategy":"validation","validationCode":"const RESERVED = ['CROSS_RUNNER'];\nfunction assertPassthroughEnv(vars) {\n  for (const key of Object.keys(vars)) {\n    if (RESERVED.includes(key)) {\n      throw new Error(`${key} is reserved and cannot be passed through`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["environment","reserved-name","docker","configuration"],"backgroundTag":"reserved-environment-variable","analyzedSha":"8c1a8aa4b661711f4b7b6ac07c2e8929ce2f7d27","analyzedAt":"2026-09-13T15:10:43.988Z","contentChangedAt":"2026-09-13T15:10:43.988Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}