Skip to content

# Troubleshooting Startup

Please read this entire document before taking any action.

## Invalid Configuration Alert

If a configuration file contains errors that make it unusable/unreadable, Reactor will fall back to the last-known-good version of the file and issue an Alert. This behavior is intended to keep your system up and running, even though it may not have your latest desired configuration changes.

The most common cause of these alerts is syntax or structural errors in your YAML configuration while you are making changes -- your YAML isn't correct YAML. You can use any of many online tools to check it, for example https://yamlchecker.com. These only check to make sure that your configuration is valid YAML, they don't check to make sure that the necessary keys and values are within Reactor's requirements, but invalid YAML is exactly the problem that leads to Invalid Configuration alerts. Other errors typically don't interfere with startup and are logged in Reactor's log files.

Because many configuration files are loaded before Reactor is really up and running, console logging is used for problems reading and parsing configuration files. Typically, these messages will be routed to your system log files (e.g. `/var/log/syslog` or `/var/log/messages`). Looking in these logs may provide some insight. For Docker users, these logs live inside the container, so opening an exec shell into the container is required to access them.

If you are unable to figure out what the error is, open a new thread (don't hijack an existing thread) on the SmartHome Community. Please remember to read and follow the posting guidelines.

## Reactor Won't Start/Can't Connect to UI

If you are unable to connect to the Reactor UI, wait at least 60 seconds and try again. A slow-starting or faulting connection to a hub can delay the startup of Reactor until it times out (which is 60 seconds by default). If the UI comes up after a minute to two of trying, you have a controller issue and you need to look in the `reactor.log` file for clues as to what might be going on.

If Reactor has not come up after 60 seconds, or you can see in your system diagnostic messages that the Reactor process is restarting repeatedly (under systemd or as a docker container, for example), here are some things you can try:

- Always check the `reactor.log` file in your `logs` subdirectory for errors/exceptions.
- If you've just edited one of your Reactor configuration files and now Reactor won't start, you've probably made an error. Use a tool like https://yamlchecker.com to syntax-check your edits.
- Make sure you have sufficient free space on your storage volume(s), particular those containing the Reactor `storage` and `logs` directories. If one or more volumes has completely filled (to 100% full/0% free), do not restart Reactor! First, free up space on those volumes (make note of what your cleanups are for later), and then reboot the system. Disk full conditions may lead to crashes of many system daemons as well as corruption of data files. Always investigate why your volume has filled and take mitigating steps in your system management procedures. You may also want to add notifications using the configuration and attribute data available in Reactor's SystemController, which will track and report disk space.
- Users running Reactor under systemd or similar *nix facilities can look at their system log files in `/var/log` (e.g. `/var/log/syslog`, `/var/log/messages`, etc.) for messages related to the startup. If a hard error is preventing Reactor from starting and writing to its own log files, this is a good place to look for messages.
- Docker container users can look at the container log file. On the command line, you can use `docker logs <container-name>` (even if the container has stopped). For NAS users, I know the Synology UI has a "Logs" tab available when you click on the container and then the "Details" button. This will log startup and console messages from Reactor, so you may find something useful there. I'm sure other NAS systems have similar functions in their GUIs. NAS users should be particularly attentive to problems with the bind mounts needed for your configuration and data files; make sure they are spelled correctly, are created where they should be, and have correct permissions.
- Bare metal install users: make sure you've installed package dependencies; if you've just upgraded Reactor to a new version, you may need to do this as well (new dependencies may have been introduced). Refer to the Bare Metal Install Instructions.

- Docker container users on Raspbian Buster (Raspberry Pi OS) may need to install a patch required by the image's OS to work around the Y2038 bug (like Y2K; yes, we're approaching the next event horizon). Specifically, users of Raspbian Buster only (not Raspbian Bullseye, the version after), need to run the following commands to patch their system:

      $ sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
      $ echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
      $ sudo apt update
      $ sudo apt install libseccomp2 -t buster-backports

  You can find further information about this patch here. Current Reactor docker containers are built on Alpine 3.14.

If you can't fix the problem yourself based on what you're seeing, search the SmartHome Community to see if others are experiencing similar issues and what has been recommended. Please remember to follow the posting guidelines.

## A Rule or Reaction is Looping

"With great power comes great responsibility." — Uncle Ben (and Stan Lee)

Reactor allows you to create complex interdependencies between system objects (like Entities, Rules, and Variables/Expressions). It is therefore possible to create circuitous logic, where A depends on B, and B depends on A, and using Rules as an example, the triggering of the former triggers the latter, thus triggering the former, and so on, ad infinitum.

Reactor makes an effort to detect loops in many cases, but it's not possible or practical to detect all cases, and there are cases where you can create a loop that results in a "runaway Reactor." When Rules are involved, this often triggers throttling of the Rules involved. Sometimes, you'll just start up Reactor and instantly pin the host's CPU at 100%. An examination of the logs usually reveals the cause pretty quickly, and then it's just a matter of evaluating your logic/use to formulate a fix.

However, when Reactor goes to 100% CPU in a loop, the UI may be difficult to operate, because the server-side is so busy, preventing you from fixing the problem. In this case, just stop Reactor, and in the `engine` section of your `reactor.yaml` file, configure `enabled: false` and restart Reactor. This will bring up Reactor but not start the Engine, so the looping objects will not execute. You can then edit your Rules, Reactions, and Expressions to fix the logic and eliminate the loop. Once that's done, stop Reactor, set `enabled: true` for the Engine, and restart.

Updated: 2026-May-25