🪲 Logs and Debugging

CoolerControl runs as a systemd service. systemd-journald collects logs from services, and you can view and export them with journalctl. Use the examples below to gather logs for troubleshooting or filing bug reports.

CoolerControl Logs

• To output logs to a file in your current directory:

journalctl --no-pager -u coolercontrold -n 10000 > coolercontrold.log

• To follow current log output live in your terminal:

journalctl -u coolercontrold -f -n 200

• To change the current log level (e.g., enable DEBUG):

  Note: DEBUG produces a lot of output.

  sudo systemctl edit coolercontrold

  Then add:

  [Service]
  Environment="CC_LOG=DEBUG"

  Apply and restart:

  sudo systemctl daemon-reload
  sudo systemctl restart coolercontrold

Log levels

The GUI has two log levels: INFO (default) and DEBUG.

The daemon supports additional levels: ERROR, WARN, INFO, DEBUG, and TRACE.

By default, device changes are logged at INFO. If the volume is too high for your setup, consider switching to WARN to reduce routine output. See above for how to change the log level.

DEBUG logging

Enabling DEBUG output is invaluable for diagnosing issues. It increases verbosity across internal systems to help pinpoint root causes.

• Systemd daemon

  Use the "systemctl edit" method above to set CC_LOG=DEBUG. To remove the override, run sudo systemctl edit coolercontrold again and clear the contents, or delete the drop-in from /etc/systemd/system/coolercontrold.service.d/, then reload the daemon and restart the service.

• To manually run the daemon and capture its log output

  # make sure the systemd service is not running:
  sudo systemctl stop coolercontrold
  # (adjust paths as needed)
  CC_LOG=DEBUG sudo -E ./coolercontrold &> /full/path/coolercontrold_YYYYMMDD.log

• Desktop application only

  coolercontrol --debug

• AppImage (daemon)

  ./CoolerControlD-x86_64.AppImage --debug

liquidctl Logs

liquidctl is an upstream project that CoolerControl integrates with for many USB AIOs, fan hubs, and other devices. By default, CoolerControl sets the log level to WARN for liquidctl. You can override this by setting the LIQUIDCTL_LOG environment variable, e.g.:

[Service]
Environment="CC_LOG=INFO"
Environment="LIQUIDCTL_LOG=INFO"

Note: It will not work to set the liquidctl log level higher than the daemon's log level, as all logs are passed through the daemon.

TIP

Enabling debug logs for coolercontrold will also enable debug logs for liquidctl.

liquidctl is a Python service, so it supports all of Python's logging levels: CRITICAL, ERROR, WARN, INFO, and DEBUG.

If you encounter an issue that appears to be specific to liquidctl, please check the issue tracker and, if necessary, open a new issue with debug logs. It is recommended to use the liquidctl CLI directly and enable debug output with -g:

liquidctl -g list
liquidctl -g status