rustfs/rustfs · error · ConfigError

Failed to parse environment variable {0}: {1}

Error message

Failed to parse environment variable {0}: {1}

What it means

ConfigError::EnvParseError(name, value) reports an environment variable that exists but whose value cannot be parsed into the expected type; the message carries both the variable name and the raw value. It is built by the ConfigError::env_parse_error(key, value) constructor on strict parse paths.

Source

Thrown at crates/trusted-proxies/src/error/config.rs:27

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Configuration error types for the trusted proxy system.

use std::net::AddrParseError;

/// Errors related to application configuration.
#[derive(Debug, thiserror::Error)]
pub enum ConfigError {
    /// Required environment variable is missing.
    #[error("Missing environment variable: {0}")]
    MissingEnvVar(String),

    /// Environment variable exists but could not be parsed.
    #[error("Failed to parse environment variable {0}: {1}")]
    EnvParseError(String, String),

    /// A configuration value is logically invalid.
    #[error("Invalid configuration value for {0}: {1}")]
    InvalidValue(String, String),

    /// An IP address or CIDR range is malformed.
    #[error("Invalid IP address or network: {0}")]
    InvalidIp(String),

    /// Configuration failed overall validation.
    #[error("Configuration validation failed: {0}")]
    ValidationFailed(String),

    /// Two or more configuration settings are in conflict.
    #[error("Configuration conflict: {0}")]
    Conflict(String),

View on GitHub (pinned to 35af688cd9)

Solutions

1. Fix the value to the documented format for that variable (the error message shows both name and the exact bad value)
2. For booleans use true/false (or 1/0) as documented; for integers use plain ASCII digits without units or separators
3. Add a startup lint that pre-parses all typed RUSTFS_* variables and reports offenders in one pass

Example fix

# before
RUSTFS_TRUSTED_PROXY_MAX_HOPS="10 hops"
error: Failed to parse environment variable RUSTFS_TRUSTED_PROXY_MAX_HOPS: 10 hops

# after
RUSTFS_TRUSTED_PROXY_MAX_HOPS=10

fn parse_env_u32(key: &str) -> Result<u32, ConfigError> {
    let raw = std::env::var(key).unwrap_or_default();
    raw.trim().parse::<u32>()
        .map_err(|_| ConfigError::env_parse_error(key, raw.clone()))
}

let max_hops = parse_env_u32(ENV_TRUSTED_PROXY_MAX_HOPS)?;

fn env_parses_as_u32(key: &str) -> bool {
    std::env::var(key).map(|v| v.trim().parse::<u32>().is_ok()).unwrap_or(true)
}

match strict_load() {
    Err(ConfigError::EnvParseError(key, value)) => {
        tracing::error!(event = "config.load", result = "env_parse_failed", key = %key, value = %value, "set {key} to its documented format");
        Err(ConfigError::EnvParseError(key, value))
    }
    other => other,
}

When it happens

Trigger: A strictly-parsed numeric or boolean variable receives a malformed value - for example RUSTFS_TRUSTED_PROXY_MAX_HOPS=many, a boolean var set to yes instead of true/1, or a numeric var containing trailing whitespace or a unit.

Common situations: Values written by hand into .env files with quotes, spaces or units; copy-paste between shells that mangle quoting; booleans given as on/off/yes instead of true/false; decimal separators from locale-formatted numbers.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Missing environment variable: {0}
• Configuration parsing error: {0}
• Invalid configuration value for {0}: {1}
• erasure reader requires non-zero block size
• InvalidInput

AI-assisted analysis of rustfs/rustfs@35af688cd9 (2026-08-20). Data as JSON: /api/errors/c962bb41723e8268. Report an issue: GitHub.