Troubleshooting
Fix npm E502 when installing Node-RED nodes behind a proxy
Short answer
npm error code E502 on a palette install means an answering hop could not resolve or connect onward to the registry host, even when a generic HTTP check passes. Work the failure upstream from the proxy: confirm the proxy process, match the device's proxy address and mode, check the firewall rule, then verify outbound TCP 443 to registry.npmjs.org. Treat an App Unavailable editor as a missing localhost exception, a separate fault.
On this page
- What npm error code E502 actually reports
- Run the checks in this order
- Clear the device-to-proxy leg first
- Separate the registry route from the connection check
- Reading the 72 second E502 from a node-red-contrib-influxdb 0.7.0 install
- Clear the App Unavailable fault on older images
- Install the package offline when the route stays closed
- The decision for each symptom
- Questions asked
npm error code E502 on a Node-RED palette install is a proxy-path failure, not a Node-RED fault: an intermediary answered npm and reported that it could not resolve or connect onward to the package registry. A green HTTP connection check in the device's web interface does not clear it, because that check tested a different destination than npm's registry request. Work the failure in order: confirm the proxy process is running, match the device's proxy address and mode to the listener, confirm the firewall rule on the proxy host, then make the registry-specific outbound case to the network team. An editor that shows App Unavailable only while the proxy runs is a different fault with a different fix: a missing localhost exception in the proxy settings.
What npm error code E502 actually reports #
The palette manager does not download anything itself. It shells out to npm, and the log shows the exact line it runs:
npm install --no-audit --no-update-notifier --no-fund --save --save-prefix=~ --production --engine-strict node-red-contrib-influxdb
Read the four parts of the result separately, because only some of them are failures:
npm error code E502— npm received HTTP status 502, the code an intermediary returns when its own upstream request fails.npm error 502 6; Could not resolve or connect to proxy or host - GET https://registry.npmjs.org/node-red-contrib-influxdb— the request that failed: a GET of the package path on the npm registry, which is served over HTTPS on TCP 443.rc=1— the exit code npm handed back to the palette manager; anything nonzero means the command failed.- npm warn config production Use
--omit=devinstead. — a deprecation notice about the --production flag the palette manager still passes. It is not the failure; npm kept running for more than a minute after it.
The HTTP specification defines 502 Bad Gateway as a response from a gateway or proxy that could not get a valid answer from the server it tried to reach. So the question is never whether Node-RED is broken; it is which leg between the edge PC, the proxy and registry.npmjs.org is broken.
Run the checks in this order #
Work down the list and stop when the symptom changes:
- Read the npm log block first: note the error code, the full GET line and the exit code before changing any setting.
- Confirm the proxy process on the PC is running and listening at the moment you retry, not just earlier in the day.
- Compare the device's proxy address, port and mode against the listener. A virtual edge device on a laptop reaches the host through the hypervisor's alias: the reported setup paired http://10.0.2.2:3128 with a PC proxy listening on 3128.
- Confirm the inbound firewall rule on the proxy host permits the device's address to the proxy port.
- Confirm the proxy host can resolve registry.npmjs.org and open outbound TCP 443 to it, over the VPN too if the host rides one.
- Clear stale npm keys if the device ever sat on another network: npm config delete proxy and npm config delete https-proxy, and keep exactly one registry configured.
- Retry, then read the new timestamps; never diagnose from an old log.
Keep the branches apart while you work:
| What the log or screen shows | What it tells you | Where to work |
|---|---|---|
| Connection check passes, palette install returns E502 | the check tested a destination npm never uses | the registry-specific route |
| npm error 502, Could not resolve or connect to proxy or host | an intermediary answered and failed upstream | proxy-side DNS, outbound TCP 443, VPN path |
| npm exits within moments with a refused connection or timeout | the device never reached the proxy | proxy process, device address, firewall rule |
| npm warn config production Use --omit=dev instead. | deprecation notice, not the failure | read on to the final error |
| Node-RED editor shows App Unavailable while the proxy runs | proxy settings intercepting loopback calls | the loopback exception |
Clear the device-to-proxy leg first #
The device-to-proxy leg fails loudly and differently from E502: a stopped proxy process, a moved listening port or a firewall drop gives npm a refused connection or a connect timeout within moments, never a 502 body. It still takes two minutes to clear, so do it before anything else:
- The proxy process must be running while you retry. On the PC hosting it, check the process list and note the port it listens on.
- The device's proxy settings must name an address that reaches that PC. A virtual device uses the hypervisor's host alias, which is how the http://10.0.2.2:3128 pairing in the reported setup arises; a physical device on the plant network needs the PC's own address instead.
- The configured mode must match the topology. A virtualized device that reaches its host through a forwarded alias needs that forwarding mode selected; the alias address alone does not carry npm's CONNECT request through.
- The inbound firewall rule on the PC must permit the device's source address to the proxy port, because a live process behind a closed port behaves exactly like a dead one.
The full device-side sequence for npm access behind an HTTP proxy on an industrial edge box is walked through in the guide to setting up an edge controller behind an HTTP proxy for npm access.
Separate the registry route from the connection check #
A generic HTTP connection check proves one destination worked at that moment. npm needs the proxy to resolve one name and open one port: registry.npmjs.org on TCP 443. The error text names both endpoints — proxy or host — so decide which one failed before changing anything:
- If npm cannot reach the proxy at all, you saw refused or timeout errors, not a 502. That points back to the device-to-proxy checks above.
- If the proxy answered 502, the proxy is alive and its upstream leg failed: it could not resolve registry.npmjs.org, its outbound TCP 443 is blocked, or the path it rides is restricted.
Take the network team one concrete request: permit the proxy host outbound TCP 443 to registry.npmjs.org and permit it to resolve that name in DNS. If the host PC connects through a VPN, the proxy's upstream rides that tunnel, and a tunnel carrying only corporate destinations keeps returning 502 for the registry no matter how healthy the check looks. An internal HTTP-to-HTTPS redirector sitting between the proxy and the registry produces the same signature, so ask about that too.
Stale npm settings are the quiet variant of this failure: an old proxy or https-proxy key from a previous network keeps npm sending every request to a proxy that no longer exists. Remove the keys with npm config delete proxy and npm config delete https-proxy and keep one registry configured, because a second registry entry gives npm a second place to fail. If Node-RED was put on the box rather than shipped with a controller image, those keys live under the account that runs Node-RED, as covered in installing Node-RED natively on a Linux edge computer.
A log showing ECONNRESET instead of E502 means the proxy cut the connection mid-transfer; that break has its own walkthrough of npm ECONNRESET proxy failures.
Reading the 72 second E502 from a node-red-contrib-influxdb 0.7.0 install #
Inputs #
Taken from the palette manager log of the reported install:
- Install command issued at 2024-08-05T23:46:11.417Z.
- Deprecation warning logged at 2024-08-05T23:46:12.043Z.
- First error line at 2024-08-05T23:47:23.598Z: npm error code E502.
- Request and exit code: GET https://registry.npmjs.org/node-red-contrib-influxdb, rc=1.
The rule #
The status code decides the branch and the clock corroborates it. A 502 means an intermediary answered, so the device-to-proxy leg is alive and, by the definition of the code, that intermediary is reporting a failure on its own upstream side. A device-to-proxy break looks different: a dead listener or a wrong address is refused immediately, and a firewall drop returns a timeout — neither carries a 502 status.
Arithmetic #
Error timestamp minus command timestamp: 23:47:23.598Z − 23:46:11.417Z = 60 s + (23.598 − 11.417) s = 60 s + 12.181 s = 72.181 s, about 72 seconds. The warning at 23:46:12.043Z sits 71.555 s ahead of the error, so npm ran the whole span between warning and failure.
Result #
npm waited about 72 seconds, then exited with code E502 on GET https://registry.npmjs.org/node-red-contrib-influxdb and rc=1. The node-red-contrib-influxdb 0.7.0 tarball was never retrieved.
Decision #
Seventy-two seconds of waiting plus a 502 answer puts the break at or beyond the proxy's upstream leg: proxy-side DNS for registry.npmjs.org, or outbound TCP 443 from the proxy host, including the VPN path. Verify those before touching the device's proxy settings again, because the device reached its proxy and was told, in HTTP, that the proxy could not go further. A different signature — an exit within moments and no 502 — flips the decision to the device-to-proxy leg: process, address, firewall.
Clear the App Unavailable fault on older images #
On controllers with older Node-RED app builds, starting the proxy can take the editor offline: the app list shows App Unavailable, and stopping the proxy brings it back. Keep this separate from E502 — it is an availability fault, not a package-retrieval fault, and fixing it does not fix the install.
The known cause is a proxy exception list without the loopback name. The Node-RED app calls its own services through localhost; with no exception for it, those internal calls get pushed into the proxy and the app falls over. Add localhost to the exception or bypass list in the device's proxy settings, restart the proxy and retest the editor while it runs.
If the editor still fails, the app build is the next suspect: move to the Node-RED build the vendor pairs with your controller OS image and hold it there, using the pinning discipline described in stable Node-RED gateway flows with vendor-pinned nodes.
Install the package offline when the route stays closed #
When the network team will not open the registry path, install from a tarball. The npm registry serves every package at a fixed address: https://registry.npmjs.org/PACKAGE_NAME/-/PACKAGE_NAME-VERSION.tgz. For this failure that is https://registry.npmjs.org/node-red-contrib-influxdb/-/node-red-contrib-influxdb-0.7.0.tgz, and an older version installs by writing that version into the URL.
- Download the .tgz on a PC that reaches the registry, matching the exact package name and version.
- Copy it to the edge PC.
- In the Node-RED user directory, ~/.node-red on a Linux edge PC, run npm install ./node-red-contrib-influxdb-0.7.0.tgz.
- Restart Node-RED and reload the editor; the node appears in the palette.
Two limits matter. npm still resolves the tarball's dependencies from the registry, so a package with missing dependencies needs those mirrored first or a working route after all. And because a palette or npm install runs code on the edge PC, pull the archive from the registry itself and match the name and version against the Node-RED library listing before installing it.
The decision for each symptom #
- E502 with Could not resolve or connect to proxy or host: the proxy's upstream leg is broken. Verify proxy-side DNS for the registry and outbound TCP 443, VPN included, before touching device settings.
- Refused or timeout immediately after the install command: the device-to-proxy leg. Proxy process, device address, firewall rule.
- App Unavailable only while the proxy runs: add localhost to the exception list; if it persists, move to the app build paired with the controller image.
- Registry route permanently closed: tarball install from the registry URL, with dependencies mirrored or a route arranged for them.
Questions asked
What does rc=1 mean at the end of the palette install log?
rc is the exit code npm returned to the palette manager. A value of 1 means the npm command failed. In this failure mode the nonzero code comes from the E502 retrieval, not from the package itself: npm never obtained the tarball, so there was nothing to unpack or install. Fix the proxy path and the same command should return rc=0.
Is the npm warn config production line the error?
No. The palette manager still passes the old --production flag, and current npm prints a deprecation warning telling you to use --omit=dev instead. In the reported log the warning appeared within a second of the install starting, while npm exited with E502 about 72 seconds later. Treat the warning as noise and read the final error block and exit code for the real result.
Which proxy settings does npm actually use on an edge PC?
npm merges proxy configuration from the HTTP_PROXY and HTTPS_PROXY environment variables and the proxy and https-proxy keys in its .npmrc files. Run npm config get proxy and npm config get https-proxy as the account that runs Node-RED, because the keys are stored per user. Delete a stale key with npm config delete proxy or npm config delete https-proxy when a device moves off a proxy network.
Can I remove the proxy from an edge PC on the plant network?
Only if your network policy allows a direct outbound route. Clear the device-side proxy in its settings, clear npm's keys with npm config delete proxy and npm config delete https-proxy, then confirm the PC can reach registry.npmjs.org on TCP 443 directly before reinstalling. On a segment governed by IT, keep the approved proxy route and use the offline tarball install instead of opening unsolicited paths.
Why does a tarball install still touch the registry?
Installing a local .tgz satisfies the package itself, but npm resolves that package's dependency list from the configured registry at install time. If the dependencies are not already present in the Node-RED user directory, npm needs a working route and fails with the same proxy errors. A fully offline install therefore needs the dependency packages mirrored and installed first, or a route that works for the registry.
Where do I find the full npm debug log after a failed palette install?
The error block ends with the line 'A complete log of this run can be found in:' followed by the exact path of that run's debug log under the .npm/_logs directory of the account that ran the install. Open the file and search for the GET line and the first error entry; the timestamps in it are what you compare against the palette manager's own log.