Writing · Operations · Rust · Configuration
How a trailing space in an env file turns a security check off
REQUIRE_MANAGE_GUILD=true with a trailing space parsed as false. How lenient env parsing fails silently, and the rules that make a server refuse to boot instead.
My API server reads its settings from environment variables, like most services that run in containers. One of them, REQUIRE_MANAGE_GUILD, decides whether a signed-in user may only work with the Discord servers they have permission to manage. The env file says true. Reading the parser one day, I realised how little it would take for the running process to say false.
All it needed was a space at the end of the line. The parser compared the value with "true", would find "true ", and would do what a great deal of configuration code does with a value it doesn't recognise: use the default. Nothing would be logged. The server would start normally with the restriction simply off.
The same parser read COOKIE_SECURE, where the same mistake would drop the Secure flag from the session cookie. This article is about the rules I changed afterwards, and two related ways configuration can be wrong without anything telling you.
Lenient parsing is a silent failure
The parser had a shape most projects contain somewhere:
fn env_bool(key: &str, default: bool) -> bool {
match std::env::var(key).as_deref() {
Ok("true") | Ok("1") => true,
Ok("false") | Ok("0") => false,
_ => default,
}
}
The last arm handles two very different situations as if they were one. "The variable isn't set" is a legitimate reason to use the default. "The variable is set to something I can't read" is an operator error, and treating it as "unset" converts a typo into a behaviour change. For a boolean that guards access, the default is the dangerous direction as often as not.
Trailing whitespace is the most common way to hit it, because it is invisible in an editor and survives copy and paste. A capitalised True, a value someone wrapped in quotes, or a file saved with Windows line endings can do the same thing.
The rules now
1. Trim every value on the way in. No setting in my server has meaningful leading or trailing whitespace, so every variable is trimmed in one place before anything parses it.
2. Absent means default. Present but unparseable means the server doesn't start.
fn parse_bool(key: &str, raw: &str) -> Result<bool, ConfigError> {
match raw.trim().to_ascii_lowercase().as_str() {
"1" | "true" | "yes" | "on" => Ok(true),
"0" | "false" | "no" | "off" => Ok(false),
other => Err(ConfigError::invalid(key, other, "expected true or false")),
}
}
fn env_bool(key: &str, default: bool) -> Result<bool, ConfigError> {
match std::env::var(key) {
Err(_) => Ok(default),
Ok(raw) => parse_bool(key, &raw),
}
}
The accepted spellings are a short, closed list. Anything else is an error that names the variable and shows the value it found. The same rule applies to numbers, durations and lists: a price table that doesn't parse stops the boot, it doesn't become an empty table.
3. Fail at startup, not at first use. All configuration is parsed into one struct before the server opens a port. A deploy with a bad value fails within a second, while the previous version is still running, instead of failing for a user an hour later on the one code path that reads the setting.
A crash at boot feels harsh. It is the cheapest failure available: it happens while I am watching the deploy, and the error message says exactly which line to fix.
The second silent failure: relative paths in a container
The server keeps several small SQLite databases: short links, scheduled posts, a message library. Each has a path setting, and each originally defaulted to a bare file name such as schedules.db.
A bare file name is resolved against the process's working directory. In a container that is a directory inside the container's own writable layer, not the mounted volume. Everything works. Data is written and read back. Then the next deploy replaces the container, and the database is gone, with no error at any point, because from the program's point of view nothing went wrong.
Three changes closed that:
- The compose file passes every path explicitly with a default on the volume, for example
SCHEDULE_DB_PATH=${SCHEDULE_DB_PATH:-/data/schedules.db}. - At boot, the server checks every enabled store and logs a loud warning naming each one whose path is relative.
- A strict flag, meant for production, turns that warning into a refusal to start. A new store has to be added to the list that this check covers, so it can't be forgotten.
This matters most for features that are off by default. Switching one on later is a configuration change, made by hand on the server, long after the code review. If the feature brings its own database, its path has to be set in the same change, and the strict check is what catches it when it isn't.
The third: configuration that was valid when you wrote it
Some settings name things that exist outside your system. My server's built-in AI assistant calls a hosted model, and the model's name is a setting. The provider retires models on a published schedule. One day a name that had been working started returning 404 model_not_found.
Boot-time validation can't catch this, because the value was correct at boot. What matters is how the running code treats it. Mine originally handled it like any other rejected request: the whole call failed with a 502, which pages me, even when a configured fallback model could have answered. Now a retired model is recognised specifically. It is skipped, the next model in the chain is tried, and a warning is logged. Only when no configured model is left does the server log an error that lists every retired name, which is precisely the thing a person needs to go and fix.
The general idea: when a setting points at something external, decide in advance what "it no longer exists" should do, and make that message name the setting.
Make the effective configuration visible
Two smaller habits follow from all this:
- Log the decisions, not the secrets. A startup line that states which optional features are on, and where each store lives, turns a silent misconfiguration into something you read on every deploy. An access restriction listed as "off" in that summary is hard to miss.
- Health checks should exercise the stores. The readiness endpoint runs a trivial query against each database that is configured, with a short deadline, and reports which one failed. A store that is misconfigured or stuck shows up in monitoring instead of in a user's error message.
Summary
- Trim values. Whitespace in an env file is invisible and common.
- Unset means "use the default". Set but unreadable means "refuse to start", with the variable's name in the message.
- Parse everything before opening a port.
- In containers, give every data file an absolute path on a volume, and check for it at boot.
- For settings that name external things, handle "it's gone" explicitly and say which setting to change.
- Log the effective feature switches at startup.
