IMD SolutionComputing LibraryShop main store

How-to

Auto restart Node-RED in Docker after exit code 255

Edge computing and IIoT Published 7 min read

Short answer

Run the container with `--restart unless-stopped` so Docker restarts Node-RED on its own whenever the process exits with code 255, while a deliberate stop still holds. Then set the console log level in `/data/settings.js` to `debug` until one failure is captured, because exit 255 names an abnormal end, not the fault.

On this page
  1. What does exited (255) on the Node-RED container mean?
  2. How do I make Docker restart Node-RED automatically?
  3. Should I use always or unless-stopped on a plant-floor box?
  4. How do I add the policy to a container that already runs?
  5. Where do I set the Node-RED log level in Docker?
  6. How much extra log does debug write until the next failure?
  7. How do I verify the restart policy actually works?
  8. Is the EtherNet/IP node what causes exit 255?
  9. Questions asked

You can have the box restart Node-RED for you: run the container with --restart unless-stopped, and Docker brings it back on its own the next time the process exits with code 255, while a deliberate stop still holds. Exit 255 is an abnormal exit status, not a diagnosis, so the second half of the fix is turning the console log level in /data/settings.js up to debug until one failure is captured. The typical case: Node-RED in a container on a controller-class edge computer, chat notifications and PLC data extraction over EtherNet/IP that run fine for days, then stop until someone restarts the container by hand.

What does exited (255) on the Node-RED container mean? #

Exit 255 is the status the Node-RED process itself reported when it ended; Docker records the number but does not interpret it, and in this pattern the Node-RED log shows an EtherNet/IP communication-node error at the end.

docker ps -a lists the container as exited (255): the main process ended and returned status 255 to the runtime. That number is a catch-all for an abnormal end — the fault itself lives one layer up, in the application log. Here the last entries before the exit come from the EtherNet/IP communication node, the process ends, and the flows stay down until the container is started again by hand. What the code does tell you: the process ended itself, and the next thing to read is the log, not the code. That is enough to act on — keep the service alive automatically, and capture enough detail to name the cause.

How do I make Docker restart Node-RED automatically? #

Add --restart unless-stopped to the docker run command that creates the Node-RED container, keeping every existing option — image, volumes, ports and environment — unchanged, and Docker restarts it after each unintended exit.

  1. Record the current container's creation options while it still exists: image name, container name, port mappings, the /data volume mapping and environment variables.
  2. Stop the old container and remove it, so the name is free for the replacement.
  3. Start the replacement with the same options plus the policy flag, placed directly after docker run:
docker run --restart unless-stopped <image and options you recorded>
  1. Confirm the flows are live again: the chat notification test arrives and PLC data extraction resumes.

The policy is stored with the container and applies to every later exit without further commands. Docker's start-containers-automatically documentation is the authority on the behavior; for this case the working summary is that an unintended exit is followed by a restart.

Should I use always or unless-stopped on a plant-floor box? #

Use unless-stopped: it restarts the container after every unintended exit just like always, but a container you stopped on purpose stays stopped even when the Docker daemon restarts, which is what you want during maintenance.

Docker documents the two policies as equivalent for unintended exits; they diverge only on the deliberately stopped container. With always, the daemon brings back a container you stopped by hand the next time the daemon itself restarts — on an edge box, that means the next reboot quietly undoes your maintenance stop. With unless-stopped, that container stays down across daemon restarts and everything else returns. Decision: unless-stopped on any box you maintain remotely; reserve always for a container that must return under every condition, where no maintenance scenario needs a stop to survive a reboot.

If Node-RED runs natively on the box rather than in a container, restart handling moves from Docker's policy to the host's service manager — a different procedure that starts with installing Node-RED natively on a Linux edge computer.

How do I add the policy to a container that already runs? #

Recreate the container: the restart policy is set when the container is created, so a running Node-RED container takes the flag only when you remove it and run it again with the same options plus --restart unless-stopped.

The flag cannot be added to a container in place, which is why the earlier section records the creation options first. Node-RED's Docker setup keeps flows, credentials and settings under /data, so the recreation preserves them as long as the same volume mapping is repeated. One check before removing anything: confirm the original run actually mapped /data. If it did not, the flows exist only inside the old container, so copy them out first — that is the single step in this procedure where data can be lost.

Where do I set the Node-RED log level in Docker? #

Edit /data/settings.js in the container's data volume, set the console logging level from info to debug, and restart Node-RED once; that file is the documented configuration Node-RED loads at startup.

If /data is bind-mounted to a host path, edit the file on the host; otherwise edit it through a shell in the container. Find the logging block and set the level:

logging: {
    console: {
        level: "debug",
        metrics: false,
        audit: false
    }
}

Settings load at startup, so the container takes the change after one restart. The available levels:

Level What it records
fatal errors that make the application unusable
error errors fatal to a single request
warn non-fatal problems
info general running information — the everyday level
debug detail beyond info — the capture level
trace very detailed logging — the stepped-up level
off no log messages

Decision: run at debug from now until the first captured exit; step up to trace only if the captured window closes without the failing call visible; return to info once you have the evidence. Trace records far more than debug, so treat it as a short window, not a standing level.

How much extra log does debug write until the next failure? #

For an illustrative flow writing 10 debug lines per minute that fails after 3 days, debug captures about 43,200 lines — roughly 8 MiB — which an edge box with gigabytes free absorbs without planning.

The arithmetic, with rates you replace with your own: 10 lines/min × 60 min/h = 600 lines/h; 600 lines/h × 24 h/day = 14,400 lines/day; 14,400 lines/day × 3 days = 43,200 lines. At an assumed 200 bytes per line, 43,200 × 200 B = 8,640,000 B, and 8,640,000 ÷ 1,048,576 ≈ 8.2 MiB. The rates are assumptions — the real figure comes from your own log — but the conclusion is scale-free: days of debug output are megabytes on boxes that count free space in gigabytes. A two-week interval at the same rates gives 201,600 lines × 200 B ≈ 38 MiB, still trivial. Decision: leave debug on until the exit happens; storage is not the constraint.

How do I verify the restart policy actually works? #

Watch docker ps -a after the next exit: with the policy in place the container shows up again rather than resting at exited (255), and the chat test message confirms the flows came back with it.

  1. After recreating the container, check docker ps -a shows it running and send the chat test message to confirm the flows are live.
  2. Verify the deliberate-stop half of the policy: stop the container on purpose and confirm it stays down. Do this in a quiet moment — it stops the flows.
  3. Start it again and let it run. After the next real exit, check docker ps -a within a few minutes: the container should be up again, not parked at exited (255).
  4. Note the exit timestamp, then save the log lines from the minutes before it — that window carries the EtherNet/IP error detail.

The policy also covers the reboot path: when the edge box restarts, the daemon starts and the container returns with it, provided it was running when the box went down. If the direction you need is the opposite — rebooting the host from inside Node-RED — that is a separate procedure, covered in rebooting the host PC from Node-RED running in a container.

Is the EtherNet/IP node what causes exit 255? #

The log associates the exit with an EtherNet/IP communication-node error, and that is as far as the evidence goes: association, not proof — the debug capture that the restart policy now guarantees is what turns association into cause.

An unhandled error in a communication node can end the whole runtime, and a dropped PLC session is a plausible trigger, but the same symptom also fits a network interruption the node merely reports first. Read the capture in this order: the last entry before the exit names the failing call; the entries before it show whether the PLC session dropped, timed out or errored on data; the gap between the first error and the exit says whether it was one hard failure or a slow degradation. Decision by case: a repeatable session failure points at the link between the box and the PLC — cable, switch port, the PLC's own state; a one-time unhandled error at a single timestamp points at handling that error in the flow instead. The restart policy is the recovery; the captured log is the fix; run both until the log answers.

Questions asked

Will the container also come back after the edge PC reboots?

Yes. Unless-stopped brings the container back when the Docker daemon starts after a reboot, provided you had not stopped the container deliberately beforehand. That is the documented behavior of this policy: a container stopped on purpose stays stopped, everything else returns with the daemon.

What happens with always instead of unless-stopped after I stop the container?

With always, a container you stopped manually is started again the next time the Docker daemon restarts, for example at the next reboot of the edge box. Unless-stopped leaves it down. On a plant-floor box you maintain remotely, that difference is the reason to choose unless-stopped.

Do I lose my flows when I recreate the container with the restart flag?

No, as long as you repeat the same /data volume mapping in the new docker run command: flows, credentials and settings live in that volume, not in the container itself. If the original container ran without a /data volume, copy the flows out before you remove it.

How long should I leave debug logging enabled?

Until one failure is captured, then return the level to info. At an illustrative 10 debug lines per minute, a three-day capture window is about 43,200 lines, roughly 8 MiB, so waiting costs almost nothing. Step up to trace only if the debug window closes without the failing call visible.

Does exit code 255 mean Docker stopped the container?

No. The 255 is the exit status the Node-RED process itself reported when it ended abnormally; Docker records the number in docker ps -a without interpreting it. The reason for the exit is in the Node-RED log, which in this pattern ends with an EtherNet/IP communication-node error.

Keep reading

  • How-to

    Run Python and Node-RED beside PLC code on an edge PC

    Keep the IEC 61131-3 program in the controller runtime and run Python and Node-RED as separate Docker containers on the same edge PC. Exchange data over one MQTT interface with a fixed publish period, and declare data stale after three missed periods. One container per workload, and nothing from Python or Node-RED inside the control project.

    Edge computing and IIoT

  • How-to

    Log production data from a panel PC to SQL Server

    Run Node-RED on the panel PC, read the production values straight from the controller, and insert one row per event into SQL Server with the mssql-plus node. Keep the panel's CSV-plus-FTP file relay only as a fallback, block duplicates with a last-record check and a unique key, and expect about 86,400 rows, roughly 8.6 MB, per day at one record per second.

    Edge computing and IIoT

  • Troubleshooting

    Fix MQTT sensor data missing in Node-RED

    A green MQTT connection in Node-RED proves only a broker session, not that the GSM module published a value or that the flow subscribes to its topic. An http in node cannot receive MQTT publications at all: use an mqtt in node. Trace RS-485 acquisition, publish result, broker identity and topic match in order, and fix the first stage with no positive result.

    Edge computing and IIoT