{"id":11444,"library":"node-red-contrib-env","title":"Node-RED Environment Variable Reader","description":"This package provides a dedicated Node-RED node (`process-env`) for retrieving environment variables from the server process where Node-RED is executing. It serves as a fundamental utility for integrating Node-RED flows with their host environment, enabling external configuration without modifying the flow directly. The node, currently at stable version 1.0.2, simplifies accessing `process.env` values compared to using a generic Function node. Its release cadence is typically driven by bug fixes or minor compatibility updates. A key differentiator is its straightforward configuration within the Node-RED editor, allowing users to specify the environment variable key directly or infer it from incoming message properties (`payload` or `topic`), with a clear order of precedence. This makes it a go-to solution for parameterizing Node-RED applications.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/lochbrunner/node-red-contrib-env","tags":["javascript","node-red","process","env"],"install":[{"cmd":"npm install node-red-contrib-env","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-contrib-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-contrib-env","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this is a Node-RED 'contrib' package and requires a Node-RED runtime to function.","package":"node-red","optional":false}],"imports":[{"note":"Node-RED 'contrib' packages are installed via npm/yarn into the Node-RED runtime and appear in the editor palette; they are not imported directly into user JavaScript code like a typical library.","wrong":"import { EnvNode } from 'node-red-contrib-env';","symbol":"node-red-contrib-env","correct":"npm install node-red-contrib-env"},{"note":"After installation, the 'process-env' node becomes available in the Node-RED editor's palette under the 'utility' category for drag-and-drop use.","symbol":"Node-RED palette","correct":"Add 'process-env' node from the palette in Node-RED editor."}],"quickstart":{"code":"[{\"id\":\"e05f2e82f7169f4b\",\"type\":\"inject\",\"z\":\"0453347f311c6264\",\"name\":\"Trigger\",\"props\":[{\"p\":\"payload\"},{\"p\":\"topic\",\"vt\":\"str\"}],\"repeat\":\"\",\"crontab\":\"\",\"once\":false,\"onceDelay\":0.1,\"topic\":\"\",\"payloadType\":\"date\",\"x\":120,\"y\":80,\"wires\":[[\"715d31518f888f4c\"]]},{\"id\":\"715d31518f888f4c\",\"type\":\"process-env\",\"z\":\"0453347f311c6264\",\"name\":\"Read MY_ENV_VAR\",\"key\":\"MY_ENV_VAR\",\"x\":340,\"y\":80,\"wires\":[[\"ed27fb47184209c1\"]]},{\"id\":\"ed27fb47184209c1\",\"type\":\"debug\",\"z\":\"0453347f311c6264\",\"name\":\"Debug Output\",\"active\":true,\"tosidebar\":true,\"console\":false,\"tostatus\":false,\"complete\":\"payload\",\"targetType\":\"msg\",\"statusVal\":\"\",\"statusType\":\"auto\",\"x\":570,\"y\":80,\"wires\":[]}]","lang":"json","description":"This Node-RED flow demonstrates reading an environment variable. First, ensure the environment variable `MY_ENV_VAR` is set in the Node-RED server's environment (e.g., `export MY_ENV_VAR='Hello from Env!'` before starting Node-RED). The Inject node triggers the flow. The 'Read MY_ENV_VAR' node (`process-env` type) is configured to look for a variable named `MY_ENV_VAR`. The Debug node displays the retrieved value (or `undefined` if not found) in the Node-RED debug sidebar."},"warnings":[{"fix":"Restart the Node-RED instance after modifying environment variables to ensure the changes are picked up by the runtime. For Docker, this means restarting the container.","message":"Environment variables are read from the Node-RED server process at startup, not from the browser running the editor. Changes to environment variables require a Node-RED restart to take effect.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Clearly define a single source for the environment variable key to avoid ambiguity. If you intend to use `msg.payload` or `msg.topic`, ensure the node's `key` property is left blank. Alternatively, use a preceding Change node to normalize the incoming message if necessary.","message":"The node determines the environment variable key using a specific precedence: first, the `key` configured in the node's properties; second, `msg.payload`; and third, `msg.topic`. If all three are present, the node's `key` property takes priority. This can lead to unexpected behavior if multiple sources are used simultaneously.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If dynamic access to environment variables within a flow is required, consider using a Function node with `process.env.MY_VAR`, or Node-RED's built-in `$env()` function in Change nodes or `env.get()` in Function nodes, which are also evaluated at runtime. For configuration that truly needs to change at runtime *without* a Node-RED restart, consider using flow or global context, or external databases/APIs, rather than environment variables.","message":"Unlike some other Node-RED mechanisms (e.g., Change node's `$env()` function, TypedInput widget with `${VAR}` syntax), this specific `process-env` node does not support dynamic updates of environment variables during flow execution. The values are resolved when the node is processed.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure Node-RED is running in a standard Node.js environment where `process.env` is accessible. This error is rare for this specific node unless the Node-RED installation itself is corrupted or running in an unusual sandbox.","cause":"The Node-RED runtime environment, or the way `process.env` is accessed by the node, might be misconfigured or the Node.js `process` global object is unavailable in a specific context.","error":"Cannot read property 'env' of undefined"},{"fix":"Verify that the environment variable is correctly set in the operating system or environment where Node-RED is launched (e.g., `export MY_VAR=value` in shell, `Environment=` in `systemd`, or defined in Docker Compose). Double-check for typos in the variable name within the node's configuration. Use a Debug node before the `process-env` node to ensure `msg.payload` or `msg.topic` contains the expected variable name if those inputs are being used.","cause":"The environment variable specified in the node configuration (or via `msg.payload`/`msg.topic`) was not found in the Node-RED server's `process.env`.","error":"msg.payload is undefined (or null) after process-env node"}],"ecosystem":"npm"}