IMD SolutionComputing LibraryShop main store

Troubleshooting

Fix Node-RED Docker x509 Certificate Expired on an Edge PC

Edge computing and IIoT Published 6 min read

Short answer

The error x509: certificate has expired or is not yet valid means Docker reached the registry over TLS but the controller clock falls outside the certificate's validity dates. Set the correct date and an NTP server, confirm the controller shows the right UTC time, and re-run the same docker run command — the pull verifies on the next connection. Change nothing else first.

On this page
  1. What the three error lines actually say
  2. Set the clock, then pull again
  3. Worked example: a 1970 epoch clock against a 90-day registry certificate
  4. When the date is right and the error stays
  5. Keep the fix across power cycles
  6. Questions asked

The error x509: certificate has expired or is not yet valid on a first-boot edge controller is a clock fault, not a Docker fault. The daemon reached the registry over HTTPS and rejected its certificate because the controller's own date sits outside the certificate's validity period. Set the date, configure an NTP server, confirm the time, then re-run the same docker run — the validity check runs on every new TLS connection, so the pull verifies immediately. In the reported case the controller simply had no NTP server configured. Change nothing else, not the image, not the port mapping, not the volume, until the clock reads right.

What the three error lines actually say #

  • Unable to find image 'nodered/node-red:latest' locally — Docker went looking remotely. The image name resolved; nothing is wrong with it.
  • docker: Error response from daemon: Get https://registry-1.docker.io/v2/ — the daemon reached the registry endpoint over the network. DNS, routing and the TCP path all work.
  • x509: certificate has expired or is not yet valid — TLS verification failed on the validity dates, and those dates are compared against the controller's clock, because a TLS handshake has no other source of "now".

The message names both failure directions in one string: a clock earlier than the certificate's start date and a clock later than its end date both produce it. On a controller booted for the first time, the clock is essentially always early. The same stale date stops licensed software identically, and an NTP time sync fix for a license not-yet-valid error documents that twin failure.

Set the clock, then pull again #

  1. Read the controller's date and time on its web management page or with date -u in a shell, and compare it with a known-good clock. Check the year first: a controller with no NTP server and no battery-backed real-time clock comes up on a power-on default, often years in the past.
  2. Set the time zone and point the controller at the plant's NTP source — the same server the PLCs and SCADA hosts already use. The address is a site value; reuse the existing source rather than introducing a second one.
  3. Confirm the controller now shows today's UTC date and roughly the right time of day.
  4. Re-run the pull. No daemon restart is needed: each pull opens a fresh TLS connection, and the validity check reads the clock at that moment.
  5. Confirm the container is running (docker ps) and that the editor answers on port 1880.

The retry command keeps what the failing one needed and drops what it did not:

docker run -d --name node-red -p 1880:1880 -v node_red_user_data:/data nodered/node-red:latest

The original command also carried --privileged=true and --user=root; the standard Node-RED image needs neither, and a privileged container on a plant controller lets one compromised flow reach devices it should never touch, so drop both unless a specific node requires them.

If the Docker daemon itself still has to be installed and the curl one-liner fails, that is the same stale clock breaking an HTTPS download from the controller side; the alternative that worked in the reported case was the vendor's .ipk package installed through the controller's web management page. Should the service then report a fault in those pages, resolving a Docker status error in the controller's web management interface is the separate follow-up.

Worked example: a 1970 epoch clock against a 90-day registry certificate #

Inputs:

  • Controller clock at first boot, NTP not configured: 1970-01-01 00:00:00 UTC — the Unix epoch, a common power-on default on a controller with no battery-backed real-time clock (illustrative of the reported case).
  • Certificate validity start: 2025-06-01 00:00:00 UTC — an illustrative issue date.
  • Certificate lifetime: 90 days — the documented validity of certificates issued by Let's Encrypt, which field reports show failing this same check.

Rule: the X.509 certificate profile in RFC 5280 requires every certificate to carry a validity interval, and requires the verifier to accept it only when the local clock falls inside that interval. The pull succeeds only when validity start ≤ controller clock ≤ validity end.

Arithmetic:

  • Validity end = 2025-06-01 + 90 days. Adding June's 30 days lands on 2025-07-01, adding July's 31 lands on 2025-08-01 at 61 days, and the remaining 90 − 61 = 29 days land on 2025-08-30 00:00:00 UTC.
  • Validity window: 2025-06-01 00:00:00 UTC to 2025-08-30 00:00:00 UTC.
  • Controller clock 1970-01-01 is earlier than 2025-06-01, so the verifier returns the not-yet-valid rejection.
  • Size of the error: 55 years × 365 = 20075 days, plus 14 leap days between 1972 and 2024 gives 20089 days to 2025-01-01, plus 31 + 28 + 31 + 30 + 31 = 151 days to 2025-06-01, so the clock is 20240 days — about 55.4 years — early.

Result: a 20240-day error against a 90-day window. No certificate in the chain can pass, and every HTTPS request from that controller fails the same way.

Decision: TLS validity needs the calendar day right and nothing finer. If the controller's date is off by a day or more, fix the time first — that alone resolves this class of pull failure. If the date is already right and the pull still fails, the fault has moved from time to trust, and the next section applies.

When the date is right and the error stays #

  • Update the controller's CA certificate bundle — the ca-certificates package on most Linux-based controllers. A controller image built before a root or intermediate rotation distrusts current registry certificates no matter what the clock says.
  • Find TLS interception. An HTTPS-inspecting firewall or an antivirus proxy between the controller and the internet re-signs registry traffic with a certificate the controller does not trust; that variant usually surfaces as x509: certificate signed by unknown authority instead of the validity message.
  • Split the fault with a workstation test: pull the same image on a machine with a correct clock. Success there clears the registry and the network path, leaving the controller's clock or trust store as the only suspects. Other image-level faults, such as a Docker shared library error on an edge PC, only become reachable after this question is settled.

Keep the fix across power cycles #

The manual date clears today's error; the NTP entry is what survives the next power cut, because the controller re-syncs at boot instead of falling back to its power-on default. Add a restart policy so the container follows the hardware:

docker run -d --restart unless-stopped --name node-red -p 1880:1880 -v node_red_user_data:/data nodered/node-red:latest

unless-stopped is a documented Docker restart policy alongside always and on-failure: it brings the container back after a reboot while still letting you stop it deliberately. If a container later exits on its own, auto restarting Node-RED in Docker after exit code 255 is the follow-up path. And if this controller should not run Docker at all, installing Node-RED natively on a Linux edge computer is the alternative route.

Questions asked

Does the same wrong clock break anything besides the Docker pull?

Yes. Every TLS connection and every license check on that controller does date math against the local clock. HTTPS downloads, HTTPS-based installers, token-based cloud logins and licensing servers can all report validity errors from the same stale date, which is why one NTP server entry fixes several symptoms at once. A licensed SCADA or IoT platform on the same box can raise its own not-yet-valid message until the clock is corrected.

How accurate does the clock need to be for the pull to succeed?

TLS only needs the calendar day right: validity windows are measured in months, so an offset of seconds is irrelevant and a wrong date is what fails the check. NTP on a plant LAN typically holds a controller within milliseconds of the time source, far tighter than the pull needs. The reason to configure NTP is persistence rather than precision, because it restores the date at every boot after a power cycle.

Can I set the date manually instead of configuring NTP?

Yes, and it clears the error within a minute, but treat it as a stopgap: the next power cycle puts the controller back on its power-on default date and every TLS check fails again. Set the date by hand to get the container running now, then add the NTP server before the panel closes, so the controller restores its own time at every boot from then on.

Why did the curl-based Docker installer fail on the same controller?

The install script downloads over HTTPS from the controller itself, so the same stale clock that broke the registry pull broke that TLS handshake too. The workaround that succeeded in the reported case was downloading the vendor's .ipk package and installing it through the controller's web management page, which moves the download to a machine with a correct clock. Fix the time first and the script route normally works again.

Does the container need --privileged and --user=root, as in the failing command?

No. The standard Node-RED image runs flows, the editor and MQTT connections without either flag. Running a privileged container on a plant controller widens what one compromised flow can reach, so add them back only when a specific node needs direct device access, and record why. Keep -p 1880:1880 and the /data volume: those make the editor reachable and the flows persistent.

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

    Set up the MQTT Client SL library on a CODESYS controller

    MQTT Client SL is part of the CODESYS IIoT Libraries SL package. Verify the exact controller runtime and its license, pin the library version, batch JSON per asset, and set the controller clock before opening a TLS session.

    Edge computing and IIoT

  • How-to

    Auto restart Node-RED in Docker after exit code 255

    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.

    Edge computing and IIoT