skip to content

A platform sets NODE_OPTIONS for a Node.js 24 service whose start command also passes flags; how does Node combine them, and what surprises follow?

level: seniorimportance: should knowfreq 30%

answer

  1. interpreted before the command line
  2. single-value versus repeatable flags
  3. an allow list, not every flag
  4. inherited like any variable

basics

~20 s

Node reads NODE_OPTIONS before the command line: a single-value flag on the command line overrides it, repeatable flags from NODE_OPTIONS come first, and a flag not allowed there, such as --env-file, stops Node at startup.

solid answer

~40 s

`NODE_OPTIONS` is a space-separated list of flags that Node interprets **before** the command-line options. A singleton flag given in both places takes the command-line value, so `--inspect=localhost:5555` beats `--inspect=localhost:4444` from the variable; a repeatable flag such as `--require` runs the `NODE_OPTIONS` instances first, then the command line's. Only flags on a documented allow list are accepted, which `process.allowedNodeEnvironmentFlags` exposes: Node exits with an error at startup for a disallowed one such as `-p`, a script path or `--env-file`. The surprises in production are scope and ordering: the variable is inherited by every Node child the service spawns with the default `env`, a `NODE_OPTIONS` line in a file loaded by `--env-file` ranks below a real one, and the allow list differs between releases, so check it on Node 24.

code

bash · 10 lines
bash
# Set by the platform
export NODE_OPTIONS='--enable-source-maps --require ./preload-a.cjs --inspect=127.0.0.1:9229'

# The service's own start command
node --require ./preload-b.cjs --inspect=127.0.0.1:9230 server.js
# Source maps on; preload-a.cjs runs, then preload-b.cjs;
# the inspector uses 127.0.0.1:9230, because the command line wins for a single-value flag

node -p "process.allowedNodeEnvironmentFlags.has('--env-file')"
# false: --env-file is not allowed in NODE_OPTIONS

go deeper

for a junior

Recall that NODE_OPTIONS holds node flags as a space-separated list, read when the process starts.

for a middle

Explain the merge order: singleton flags from the command line win, repeatable flags run NODE_OPTIONS first, and disallowed flags stop startup.

for a senior

Diagnose the production surprises: inheritance by every Node child, a dotenv copy ranking below the real variable, and allow-list differences between releases breaking a fleet.

for a principal

Set the platform's policy: which flags a shared NODE_OPTIONS may carry, how releases are checked against the allow list, and when a service's start command should own a flag instead.

## What NODE_OPTIONS is for `NODE_OPTIONS` is an environment variable holding **command-line flags for the `node` binary**. It exists for the case where you cannot edit the start command: a platform, a base image or a process supervisor launches `node server.js`, and you still need `--enable-source-maps`, a `--require` preload or a heap flag. Node has read it since v8.0.0. Its value is a **space-separated** list, and a value containing a space is quoted inside it: `NODE_OPTIONS='--require "./my path/file.js"'`. ## How it merges with the command line Node interprets `NODE_OPTIONS` first and the real command line second, and two rules follow from that order: 1. A **singleton flag** given in both places takes the command line's value. With `NODE_OPTIONS='--inspect=localhost:4444'` and `node --inspect=localhost:5555`, the inspector listens on 5555. 2. A **repeatable flag** is treated as if its `NODE_OPTIONS` instances came first and its command-line instances afterwards. `NODE_OPTIONS='--require "./a.js"' node --require "./b.js"` behaves like `node --require "./a.js" --require "./b.js"`. When Node's experimental configuration file is in use, its documented priority is: command-line options and `NODE_OPTIONS` first, then a `NODE_OPTIONS` value loaded from a dotenv file by `--env-file`, then the configuration file. ## The allow list Not every flag may appear in `NODE_OPTIONS`. The CLI reference keeps an explicit list of allowed Node options and allowed V8 options, and the documentation states that Node exits with an error when an option that is not allowed in the environment is used, such as `-p` or a script file. A few consequences that catch people: - `--env-file` and `--env-file-if-exists` are not on the list, so loading a dotenv file has to happen on the command line. - `--test` is not on the list, although many `--test-*` options are. - Flags such as `--permission`, `--allow-fs-read`, `--enable-source-maps`, `--require`, `--import`, `--inspect` and `--max-old-space-size` are allowed. `process.allowedNodeEnvironmentFlags` is a read-only `Set` of the allowed flags. Its `has()` accepts a flag with or without leading dashes and ignores anything after `=`, so `process.allowedNodeEnvironmentFlags.has('--env-file')` is a quick check on the release you actually run. ## Surprises in production - **It is inherited.** `NODE_OPTIONS` is an ordinary environment variable, and `child_process.spawn`, `exec`, `execFile` and `fork` default their `env` to `process.env`. Every Node process the service starts, including tooling it shells out to, receives the same flags: a `--require` preload runs in each of them, and a fixed inspector address is requested by each. - **Startup failure is total.** One disallowed flag, or one the running release does not know, stops the process before any code runs. A fleet-wide value written for a newer release can therefore break services still on an older one. - **A dotenv copy ranks lower.** A `NODE_OPTIONS` line in a file loaded with `--env-file` is applied, but a real `NODE_OPTIONS` in the environment wins over it, and `process.loadEnvFile` cannot set runtime flags at all because it runs after startup. - **Quoting is part of the value.** The list is split on spaces, so a path with a space must be double-quoted inside the variable, and a platform that strips those quotes turns one flag into two broken ones. - **The command line still wins** for singleton flags, so a platform default can be overridden per service without changing the platform. ## Debugging what a process actually received When a flag seems to be ignored, check each layer rather than guessing: 1. Print the variable the process saw with `node -p "process.env.NODE_OPTIONS"` under the same environment, or log it at startup. 2. Compare it with the start command; a singleton flag on the command line silently wins. 3. Ask the running release whether the flag is allowed at all with `process.allowedNodeEnvironmentFlags.has(...)`. 4. For a spawned child, check the `env` it was given; an explicit `env` object without `NODE_OPTIONS` removes the flags, and the default passes them on. ## A sensible split of responsibilities | Concern | Where it belongs | |---|---| | Flags the platform must apply to every service | `NODE_OPTIONS`, kept short and checked against the allow list | | Flags a specific service needs | the service's start command, which wins for singleton flags | | Application variables such as `PORT` | the environment or an `--env-file` | Keeping `NODE_OPTIONS` minimal limits how far its inheritance reaches, and keeping service-specific flags on the command line keeps them visible in the place people look first.

  • Where does a NODE_OPTIONS line inside a .env file loaded with --env-file rank against a real NODE_OPTIONS variable?
    Below it. `--env-file` reads its file during startup, so a `NODE_OPTIONS` line there is applied, but a variable already set in the real environment wins over the file, and Node's documented priority puts the dotenv `NODE_OPTIONS` beneath the real variable and the command line. Loaded with `process.loadEnvFile` instead, the line has no effect on runtime flags at all.
  • A Node service shells out to a Node-based tool, and the tool unexpectedly runs the service's preload script and asks for an inspector port. Why?
    The child inherits `NODE_OPTIONS` through the default `env` of `child_process`, so the `--require` preload and the `--inspect` address meant for the service are applied to the tool too, and the tool requests an address the service already holds. Pass the child an `env` without `NODE_OPTIONS`, or keep `--inspect` on the service's own command line rather than in the shared variable.

  • NODE_OPTIONS overrides whatever flags the start command passes.
  • Any node flag, including --env-file, can be placed in NODE_OPTIONS.
  • NODE_OPTIONS affects only the process the platform launches, never its children.
  • A NODE_OPTIONS line in a file loaded with process.loadEnvFile changes runtime flags.
  • Repeatable flags in NODE_OPTIONS replace the ones on the command line.

Assumes Node 24: the set of flags allowed in NODE_OPTIONS changes between releases (for example --permission-audit joined it in v24.20.0), so check process.allowedNodeEnvironmentFlags on the release you run.