Troubleshooting Time

Please read this entire document before taking any action.

In the Reactor UI's top bar, to the right of its connection state indicator, are two clocks. The upper clock is your local browser time, and the lower clock is the host time (that is, the time on the system running Reactor).

First Steps

If the two clocks do not display the same time within a few seconds, are you (and your browser) in a different time zone from the Reactor host at the moment? If you are sitting in San Francisco, California checking in on your house in Bar Harbor, Maine (three time zones distant), it would be expected to see a three hour time difference between the upper and lower clocks, as you and the host are in two different time zones that are three hours apart.

Have you hard-refreshed your browser?

Hover over the times displayed. This will display a tooltip with the time zone configured for the host and browser. If the browser time or time zone is incorrect, that's an issue local to your browser/PC configuration, which won't be addressed here. Refer to the docs for your browser and operating system.

All automations run in the time of the host. If an automation is set to trigger between 1pm and 3pm, that means between 1pm and 3pm on the host. The rest of this document is only concerned with issues of host time. Host time problems are usually one of the following:

Your host system has incorrect time zone settings/configuration (often just a typo in the name, incorrect selection, or not set at all);
Your host system is not synchronizing to network time (NTP or an equivalent service is not configured, or not updating often enough);
Your time zone data or operating system libraries/packages are out of date (make sure all of the latest OS updates are installed);
You may have test_time set in your reactor.yaml configuration (in the engine section). This configuration setting can be used to help test time-based tasks by forcing Reactor to think it is whatever time you set, but if you forget to remove it after testing, your system will forever run in this time warp ("Dormammu, I've come to bargain!").

To check the host system's time configuration as the Reactor Engine (server side) sees it, request http://your-host-ip:8111/diag/sun in a browser. This will display Reactor's interpretation of the time zone and location settings and show you the current host time and solar event times for that day. If these are not correct, proceed to the section below that applies to how you installed/run Reactor.

Docker Container Troubleshooting

Check the time at your host system first. If it's a NAS, check the time configuration in its configuration UI. If it's a standalone system like an RPi, a VM, or otherwise something you can get console (e.g. via SSH) access to, use its date or equivalent command to check the system time. If that's incorrect, that's what you need to fix (it may be that NTP or an equivalent service to synchronize the time to well-known servers hasn't been configured). Refer to the documentation for your system hardware and software for getting correct time and time zone configuration.

Tip

Most modern Debian- and Ubuntu-based systems have a timedatectl command you can run that will display the current time, the configured time zone and its offset, and the status of NTP/synchronization all in one step. If this isn't showing what's expected, consult your operating system docs for instructions on properly setting the time zone and configuring NTP or an equivalent service.

Docker containers each have their own time zone configuration that is completely independent of the host's configured time zone (i.e. they don't inherit the time zone from the host). It is quite common to see a host system correctly configured for a local time zone and yet see every docker container running in the default UTC time zone, and since many containers don't really care about time operationally, you may never notice. Reactor cares, though. Even if you've set it before, when upgrading Reactor, it often happens (particularly, it seems, among users using Portainer) that the time zone setting is lost during the upgrade.

To check the time zone configuration for the container, look at the output of the diag/sun query you did above. If the query result shows env TZ=undefined (ignore ICU TZ=; it doesn't matter for docker), or a time zone other than expected, then you have not properly completed the install steps for the container. The Reactor installation documentation for docker containers gives specific instructions for setting the correct time zone for the Reactor container.

Bare-Metal Troubleshooting

If you are running Reactor in a "bare-metal" install (i.e. not under docker), you can check how nodejs is interpreting your time zone configuration by the following command on the host command line:

/path/to/node -e 'console.log(new Date().toLocaleString())'

Make sure /path/to/node uses the same path that Reactor uses to run the correct version of nodejs. This isolates Reactor from the troubleshooting, displaying only what nodejs learns from your system configuration. Reactor relies entirely on nodejs for time zone and DST interpretation, so if nodejs displays incorrect time, Reactor will as well. If the displayed time is incorrect by an hour or more, you almost certainly have an error in your system time zone configuration. Consult your OS docs to figure out how to set it (e.g. on Raspberry Pi, it's typically done through raspi-config).

Typical Linux Configuration

These days, it seems most Linux systems have standardized on having /etc/localtime be a symbolic link to a time zone data file somewhere in /usr/share/zoneinfo. You can use ls -l /etc/localtime to see that. If localtime is linked to the wrong data file, you can relink it to the correct one (e.g. ln -sf /usr/share/zoneinfo/America/New_York /etc/localtime) and reboot. This is often enough, but YMMV depending on your hardware and OS. You should also check the TZ environment variable with the echo $TZ command. If TZ is not set (output is blank), that's usually not a problem as long as /etc/localtime is correct. If TZ is set, it must agree with /etc/localtime; if not, that needs to be reconciled.

If the time zone settings for the host seem correct but the time is not accurate (i.e. it's off by less than an hour), it's likely that your host system is not running ntpd or an equivalent service, or the service has stopped for some reason. The ntpd service synchronizes your host system to well-known network time servers. Most new OS installations will install ntpd or an equivalent service to start at boot, but it's still worth checking into. That's OT for this document; please see the documentation for the OS you are using.

Raspberry Pi's and many other Debian- and Ubuntu-based systems have a timedatectl command you can run that will display the current time, the configured time zone and its offset, and the status of NTP/synchronization all in one step. If this isn't showing what's expected, consult your operating system docs for instructions on properly setting the time zone and configuring NTP or an equivalent service.

If everything seems right but nodejs and Reactor will just not show the correct host time, you can try forcing the time zone for nodejs by setting the TZ environment variable in the Reactor runtime environment. That depends on how you are starting/running Reactor.

If you are using systemd to run Reactor as a daemon (i.e. you use the systemctl command to start/stop it manually), which is the case when you've used the RPi installation script in the tools directory to install Reactor, but also possible on many Linux variants, you can modify the startup configuration for the daemon to force the TZ value as follows:

Log in to your host system (command line);
Open /etc/systemd/system/reactor.service in your favorite plain text editor (not Word or WordPad, these will damage the file!). The name given here is the default, typical name; yours may be different if you set up the service in systemctl yourself (i.e. didn't use the RPi install script). Tip: it's always a good idea to first make a backup of any file in /etc that you're about to edit.
Find the Environment=NODE_PATH=... line in the file.
Insert the following line after it:
```
Environment=TZ=America/New_York
```
Substitute your time zone for America/New_York as needed; capitalization and punctuation are important!
Save the file and exit the editor.
Run sysctl daemon-reload to reload the modified configuration file.
Run systemctl restart reactor to restart Reactor with the new configuration.
Go back to diag/sun to check the time and time zone. You should now observe that env TZ= in the output gives the value you specified for TZ in step 4 here.

Another option (less desirable) is to set the TZ environment variable system-wide. Do this only if you are not running Reactor under systemd.

Log in to your host system (command line);
Open /etc/profile in your favorite plain text editor (not Word or WordPad, these will damage the file!). Tip: it's always a good idea to first make a backup of any file in /etc that you're about to edit.
At the bottom of the file, add the following line:
```
TZ=America/New_York ; export TZ
```
Substitute your time zone for America/New_York as needed; capitalization and punctuation are important!
Save the file and exit the editor.
Restart the system.
Go back to diag/sun to check the time and time zone. You should now observe that env TZ= in the output gives the value you specified for TZ in step 3 here.

Requesting Support

If you can't figure it out and need post an inquiry for help in the SmartHome Community, be sure to include all of the required elements from the posting guidelines, as well as the output of your diag/sun query (above), the first 20 or so lines of a startup from reactor.log, and the output of your node -e command (above, if bare-metal). Remember, more information is better than less, and a clear description of the problem is a must, so take the time to gather and communicate what's needed up front (the rule: the effort the community makes to answer your question will be proportional to the effort you make asking it).

Updated: 2024-Mar-15