Config that lies to you

Configuration bugs are disproportionately expensive, because configuration is the layer where being wrong produces no error. The code is fine. The values are fine. The relationship between them is wrong, and nothing is designed to notice.

Three we've hit recently, each of which cost more than it should have.

1. The environment file that quietly wins

Most frameworks load several environment files in a defined precedence order. Linking a project to a hosting provider often writes an additional file as part of setup — and that file may sit higher in the precedence chain than the one you've been editing.

The symptom is maddening: you change a value, restart, and the old value is still in effect. You check the file. The file is correct. The application disagrees.

Two habits prevent it. Know your framework's precedence order — actually look it up rather than assuming. And when a value seems stuck, print it at runtime rather than reading files, because the running process is the only authority on what it actually loaded.

There's a related trap in naming. A file named for the production environment may be auto-loaded during local production builds, silently overriding local values. If you keep a template of deployment variables in the repository, name it something the framework does not recognize.

2. The theme block that emits nothing

Modern CSS frameworks let you declare design tokens in a configuration block. Some variants of that syntax generate utility classes without emitting the underlying custom properties.

So the utilities work, your tokens appear to be defined, and then a hand-written rule referencing the same token resolves to nothing. Text disappears or falls back to a browser default, and no tool reports an error, because a CSS custom property that doesn't exist is not an error — it's just empty.

The diagnostic is direct: open developer tools, inspect the element, and look at computed styles. If the variable isn't listed, it was never emitted. Declare it explicitly in a root rule alongside the framework block.

3. The script that dies on a punctuation mark

We wrote a script with an em dash in a comment. On the target machine it failed with a parse error pointing at a line that was obviously valid.

The cause was encoding. Older shells on Windows assume the system code page rather than UTF-8 when a file has no byte-order mark, so a multi-byte character arrives as mojibake — and if that lands inside a quoted string, the quoting breaks and the parser fails somewhere unrelated.

The rule we adopted: scripts intended to be run by a person on a Windows machine are ASCII-only. No em dashes, no smart quotes, no arrows, no accented characters — not in code, not in comments, not in output strings. Hyphens and straight quotes cost nothing and always work.

A parse error on a line that looks correct is almost never about that line. Check the encoding before you check the logic.

What connects them

In all three cases the system did exactly what it was designed to do, and the design included no way to tell you that your expectation was wrong.

Which suggests a general defence: when configuration behaves unexpectedly, stop reading the config and start asking the running system what it sees. Print the variable. Inspect the computed style. Dump the bytes. The gap between the file and the process is where these bugs live, and you cannot find it by staring at the file.