A limit read as Number(process.env.X ?? 500) is 0 in the container

Symptom

A setting that should fall back to its default is 0 instead, and the feature behind it stops working without an error. In the incident this unit comes from:

• every invitation request was answered "full" (the waiting-list cap was 0);
• no notification mail went out (the per-day mail cap was 0).

The code looked right:

const NOTICES_PER_DAY = Number(process.env.INVITE_NOTICES_PER_DAY ?? 20);
const WAITING_MAX = Number(process.env.INVITE_REQUESTS_MAX ?? 500);

and .env didn't set either variable. Run outside Docker (or in a unit test), the defaults applied. A test suite that drove the feature on a throwaway compose stack caught it before release.

When it happens

The compose file forwards the variable with an empty default, a common way to make "optional" settings visible in one place:

services:
  api:
    environment:
      INVITE_REQUESTS_MAX: ${INVITE_REQUESTS_MAX:-}    # empty = 500

Reproduced with Docker Compose v5.4.0 and Node 22.23.3, the host variable unset:

Cause

?? only replaces null and undefined. An empty string is a value, so Number("" ?? 500) is Number(""), which is 0, not NaN. How the common reads behave (Node 22):

So the same line means "default" in a plain shell and "zero" behind compose. A cap of 0 rarely throws. It refuses everything quietly.

Fix

In the code, treat blank as unset. The minimal change the reference project made:

// (|| and not ??: compose passes an unset variable as "", which is no number.)
const NOTICES_PER_DAY = Number(process.env.INVITE_NOTICES_PER_DAY || 20);
const WAITING_MAX = Number(process.env.INVITE_REQUESTS_MAX || 500);

|| keeps an explicit "0" (a non-empty string is truthy), so "0 = no cap" settings still work. It doesn't protect against " " or "abc". A stricter helper, also from the same codebase:

const num = (v: string | undefined, d: number) =>
  (v !== undefined && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : d);
export const SIM_FLOOR = num(process.env.SEARCH_SIM_FLOOR, 0.845);

Or fix it in compose: put the default there (${X:-500}), or use the list form (- X) so an unset variable stays unset. Putting the default in compose means it now lives in two places (code and compose), so fix the code as well.

Verify

Ask the running container, not your shell:

docker compose exec api node -p 'JSON.stringify(process.env.INVITE_REQUESTS_MAX)'   # "" is the trap

Then test the feature end to end on a stack started from the real compose file with a minimal .env. In the reference incident a unit test of the code would have passed. The suite that ran the invitation flow on a fresh compose stack is what failed.

Notes

• Search the code for the pattern: grep -rnE 'Number\(process\.env\.[A-Z_]+ \?\?' src/. parseInt(process.env.X ?? "500") is safer by accident (parseInt("") is NaN), but a NaN limit compares false against everything, which may be just as silent.
• Booleans have the same trap the other way: process.env.FLAG ?? "true" is "" behind compose. Decide what blank means and write it down next to the variable in compose.