Skip to content

Linux Troubleshooting

Jump to bottom
oxGorou edited this page Jun 11, 2026 · 11 revisions

Linux Troubleshooting

This page covers the most common problems people run into. If your issue isn't here, check the daemon logs first. They usually tell you exactly what went wrong.

Reading the daemon logs

Before trying anything else, check what the daemon is actually saying:

journalctl -u uxtu4linux.service -n 100 --no-pager

For a live stream:

journalctl -u uxtu4linux.service -f

Every preset apply is logged with its trigger, for example:

Applied preset 'Eco' (power source changed from AC to battery).
Applied preset 'Gaming' (selected in the app).
Applied preset 'Balance' (restoring saved settings at startup).

Enable debug logging for more detail (toggle Debug in Settings, or edit the config directly):

# Assets/config.ini
[Settings]
debug = 1

Then restart the daemon:

sudo systemctl restart uxtu4linux.service

Daemon issues

Daemon is not running / TUI says "Not running"

Try starting it:

sudo systemctl enable --now uxtu4linux.service

Check the status:

systemctl status uxtu4linux.service

If it failed to start, the status output shows the last few log lines. Check the full logs:

journalctl -u uxtu4linux.service -n 50 --no-pager

Common causes and fixes:

What you see in the logs Fix
ryzen_smu not installed. Install ryzen_smu, see Linux Installation
ryzen_smu version X.X.X is too old (minimum: 0.1.7). Update ryzen_smu, same guide
ryzen_smu installed but not signed for Secure Boot. Enroll the signing key, see the Secure Boot section below
ryzen_smu installed but not loaded. Run sudo modprobe ryzen_smu then restart the service
dmidecode not found in PATH — hardware detection unavailable. Install dmidecode for your distro
Another daemon instance is already running (lock: /run/uxtu4linux_daemon.lock). A previous daemon instance is still running. Kill it: sudo pkill -f daemon.py
Cannot bind IPC socket ipc:///run/uxtu4linux.sock: The socket may be stale or held by another process. Run sudo rm /run/uxtu4linux.sock then restart the service
Cannot remove stale socket /run/uxtu4linux.sock: Permission problem on the socket file. Run sudo rm /run/uxtu4linux.sock then restart the service

Daemon starts but exits immediately

Check the full logs for the reason. If you see Cannot bind IPC socket or Cannot remove stale socket:

sudo rm /run/uxtu4linux.sock
sudo systemctl restart uxtu4linux.service

If you see Python tracebacks, something is wrong with the installation. Reinstalling is the quickest fix:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/UXTU4Linux/main/install.sh | bash

Service keeps restarting / flapping

The unit has Restart=on-failure and RestartSec=5. If it's cycling, look at the logs to see why it's crashing. The fix depends on the error.

To stop the restart loop while debugging, run the daemon directly in a terminal where you can see its output:

sudo systemctl stop uxtu4linux.service
sudo /opt/uxtu4linux/venv/bin/python3 /opt/uxtu4linux/src/Assets/Modules/daemon.py

TUI can't connect after the daemon is running

Make sure the socket exists. The default path is /run/uxtu4linux.sock:

ls -la /run/uxtu4linux.sock

If it doesn't exist, the daemon isn't fully started yet. Wait a few seconds and try again.

If the socket exists but the TUI still can't connect, check the permissions. The socket should be world-writable (the daemon sets mode 666 on it at startup):

stat /run/uxtu4linux.sock

ryzen_smu issues

ryzen_smu is not installed

The daemon will not start without it. See Linux Installation for full build instructions per distro.

Quick version:

# Install build dependencies first (this example is Debian/Ubuntu)
sudo apt install cmake gcc g++ dkms openssl

# Build and install
git clone https://github.com/amkillam/ryzen_smu
cd ryzen_smu
sudo make dkms-install
sudo modprobe ryzen_smu

ryzen_smu version is too old

The minimum required version is 0.1.7. Check what you have:

cat /sys/kernel/ryzen_smu_drv/drv_version

If it's older, update it:

cd ryzen_smu    # your existing clone, or clone it fresh
git pull
sudo make dkms-uninstall   # remove the old version from DKMS
sudo make dkms-install     # install the new version
sudo modprobe -r ryzen_smu
sudo modprobe ryzen_smu

modprobe fails with "Operation not permitted"

Secure Boot is on and the module isn't signed. See the Secure Boot section below.

modprobe fails with "Module ryzen_smu not found"

The module isn't installed for the running kernel. This can happen if:

  • You updated your kernel and DKMS didn't rebuild the module
  • You installed the module for a different kernel version
  • The kernel headers for your running kernel aren't installed

Check the DKMS status:

sudo dkms status

If you see something like ryzen_smu/X.X.X: added but not installed, force a rebuild:

sudo dkms install ryzen_smu/$(sudo dkms status | grep ryzen_smu | cut -d, -f1 | cut -d/ -f2)

Or just reinstall from source:

cd ryzen_smu
sudo make dkms-uninstall
sudo make dkms-install
sudo modprobe ryzen_smu

ryzen_smu loads but /sys/kernel/ryzen_smu_drv/ is missing or empty

Try unloading and reloading the module:

sudo modprobe -r ryzen_smu
sudo modprobe ryzen_smu
dmesg | tail -20

Check dmesg for errors from the module. If the module loaded but the sysfs directory is empty, your CPU may not be supported by the version of ryzen_smu you installed.

Secure Boot issues

Module won't load with Secure Boot enabled

When Secure Boot is on, the kernel only loads signed modules. You need to enroll the DKMS signing key.

Check if Secure Boot is active:

mokutil --sb-state

Enroll the DKMS key:

sudo mokutil --import /var/lib/dkms/mok.pub

Set a one-time password when prompted.

Reboot and watch for the blue MOK Manager screen. It only stays on screen for a few seconds on some systems, so be ready.

In the MOK Manager:

  1. Select Enroll MOK
  2. Select Continue
  3. Select Yes to confirm
  4. Type the one-time password you set
  5. Select Reboot

After booting, verify:

sudo modprobe ryzen_smu
lsmod | grep ryzen_smu

MOK Manager screen didn't appear

This can happen if:

  • The screen timeout is very short and you missed it
  • Your firmware doesn't support MOK enrollment via mokutil

Try running mokutil --import /var/lib/dkms/mok.pub again and rebooting. If the screen still doesn't appear, check your BIOS/UEFI settings for options like "Secure Boot Key Management", "MOK Management" or "UEFI Key Enrollment".

Secure Boot is enabled and you can't enroll the key

If your system has Secure Boot locked down (common on some OEM laptops), your options are:

  1. Disable Secure Boot in BIOS/UEFI settings and reload the module
  2. Use a distribution-signed kernel module if your distro packages one
  3. Build and sign the module with your own key and add it to the UEFI Authorized Signature Database (advanced)

Hardware detection issues

Hardware type shows "Unknown"

This means the CPU was detected but has no SMU command table in the app. It could mean:

  • The CPU is too old (pre-Zen 1); ryzen_smu only covers Zen 1 and newer
  • The CPU is very new and hasn't been added to the app yet
  • dmidecode returned incomplete information

Try running hardware detection again: Settings, Re-detect hardware.

If it's still Unknown, check what dmidecode reports:

sudo dmidecode -t processor

Look at the Family and Model fields. If they're present and look reasonable, file a bug report with that output and your CPU model name.

CPU detected as wrong family or codename

Run re-detection: Settings, Re-detect hardware.

If the wrong codename persists, it may be a bug in the detection logic. File a bug with your CPU model and the output of:

sudo dmidecode -t processor | grep -E "Version|Signature|Family|Model"

Hardware detection fails because the daemon isn't running

Hardware detection proxies the dmidecode calls through the daemon, since dmidecode needs root. If the daemon isn't running, detection fails.

Start the daemon first:

sudo systemctl enable --now uxtu4linux.service

Then retry from Settings, Re-detect hardware.

dmidecode returns empty or incorrect data

Some firmware implementations have incomplete or incorrect DMI tables. This is usually a firmware bug.

Things to try:

  • Update your BIOS/UEFI to the latest version
  • Check if your distro has a newer dmidecode than what's installed

If dmidecode genuinely can't return CPU info, the app falls back to Unknown and shows limited functionality.

Preset issues

Presets apply but the CPU reverts after a few seconds

Something else is resetting the power limits. Common culprits: power-profiles-daemon, thermald, tlp, auto-cpufreq, or the kernel's own power management.

The fix is to enable Reapply in Power Management and set an interval short enough to win against whatever is competing. 3 seconds works for most setups.

Power Management, Reapply: ON Power Management, Reapply interval: 3

Presets reset after sleep/resume

The SMU loses its state on suspend. Set an On Resume preset:

Automations, On Resume, pick a preset

The daemon detects resume from suspend on its own (it compares CLOCK_BOOTTIME against time.monotonic()) and applies the resume preset automatically. You'll see a log line like Applied preset 'Balance' (woke from suspend after ~28m).

Automations aren't switching on AC/battery

Make sure Override is actually ON in Automations and that at least one slot (On AC or On Battery) is set to something other than (None).

Check that the daemon is running:

systemctl is-active uxtu4linux.service

Check the power source detection:

ls /sys/class/power_supply/
cat /sys/class/power_supply/AC*/online 2>/dev/null || cat /sys/class/power_supply/ACAD*/online 2>/dev/null

A value of 1 means on AC, 0 means on battery. If this file doesn't exist, the kernel isn't reporting AC state and the power monitor can't detect transitions.

Applied preset has no effect on performance

A few possibilities:

  • The SMU is rejecting commands. Open Power Management, Daemon status: the "Last apply" line shows whether anything was rejected, and rejected commands are marked [!] in the output below it.
  • The CPU is throttling for another reason (thermal, VRM current limit set too low, and so on).
  • Your CPU family doesn't support the specific parameter. Lines like some-arg -> not supported on HawkPoint in the apply output mean exactly that.

Custom preset shows no sections / editor is mostly empty

The Custom Preset Editor only shows sections for parameters that your CPU's SMU firmware supports. If almost everything is hidden, your CPU may be mapped to a socket type with limited command support.

Check what family the app detected:

grep -i family /opt/uxtu4linux/src/Assets/config.ini

If the family is Unknown or wrong, fix detection first. If it's correct but sections are still missing, it may be a genuine limitation of that CPU's SMU firmware.

Config and setup issues

Setup wizard runs every time I start the app

The Info section in config.ini is missing or incomplete. This usually happens after:

  • A bad update
  • Manual editing of the config file that removed required keys
  • A first run that was interrupted

Let the wizard run and complete it fully. Don't skip the hardware detection step; the Info section only gets written when detection completes.

All my settings and custom presets were wiped

If you hit "Reset all" in Settings, everything gets wiped intentionally.

If it happened without you asking for it, the Info section was broken and the app ran the wizard, which resets the config. After the next full setup completes, your settings will be fresh defaults.

Custom presets live in Assets/custom.json. Updates back it up automatically to /opt/uxtu4linux/custom.json.bak, so if a backup exists you can restore it:

cp /opt/uxtu4linux/custom.json.bak /opt/uxtu4linux/src/Assets/custom.json

config.ini is not being saved

Check that the app has write permission to Assets/:

ls -la /opt/uxtu4linux/src/Assets/

The directory should be writable by the user running the TUI. The install script chowns /opt/uxtu4linux to your user; if you installed manually with sudo, do the same:

sudo chown -R "$USER" /opt/uxtu4linux/src

Display and terminal issues

Garbled characters or weird symbols

Your terminal needs UTF-8 encoding and ANSI escape code support. Most modern terminal emulators handle this without any configuration.

Check your locale:

echo $LANG

It should be something like en_US.UTF-8. If it's C or POSIX, set a UTF-8 locale:

export LANG=en_US.UTF-8

Menus don't draw correctly or input doesn't work

The TUI uses raw terminal mode. If you're running it over SSH, make sure your TERM variable is set:

echo $TERM

If it's dumb or empty, set it:

export TERM=xterm-256color

App crashes with "stdin is not a TTY"

UXTU4Linux needs a real interactive terminal. It does not support piped input, scripts or non-interactive shells. If you see this error, run the app directly in a terminal emulator, not through a pipe or redirect.

If you're inside tmux or screen and hitting this, make sure you're attached to a live session and not running the app from a shell script.

Service path issues

Daemon starts but uses the wrong Python or the wrong script path

The service file bakes in absolute paths at install time. If you moved the app after installing, the paths go stale.

Launch the TUI once from the new location:

uxtu4linux

The TUI checks the service file at startup and rewrites it automatically if the paths don't match, then restarts the daemon.

If that doesn't work, regenerate the service file manually:

sudo systemctl stop uxtu4linux.service
sudo tee /etc/systemd/system/uxtu4linux.service > /dev/null << 'EOF'
[Unit]
Description=UXTU4Linux Power Management Daemon
After=multi-user.target

[Service]
Type=simple
ExecStart=/opt/uxtu4linux/venv/bin/python3 /opt/uxtu4linux/src/Assets/Modules/daemon.py
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl start uxtu4linux.service

Update issues

Update fails with a permission error

The updater needs to move the app directory under /opt/uxtu4linux/. It uses sudo mv internally, so you'll be prompted for your password. If sudo isn't available or the prompt fails, the update aborts with "Could not back up ... try running with sudo".

The simplest recovery is to re-run the install script, which does the same replacement with proper privileges:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/UXTU4Linux/main/install.sh | bash

Update completed but the app is broken / won't start

Your config and custom presets survive in /opt/uxtu4linux/config.ini.bak and /opt/uxtu4linux/custom.json.bak (and the updater restores them automatically on success).

If the new version itself is broken, re-run the install script to get a clean copy of the latest release:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/UXTU4Linux/main/install.sh | bash

If an update died halfway, you may find the old app directory preserved at /opt/uxtu4linux/src.bak. Restore it with:

sudo rm -rf /opt/uxtu4linux/src
sudo mv /opt/uxtu4linux/src.bak /opt/uxtu4linux/src
sudo systemctl restart uxtu4linux.service

Getting more help

If none of the above covers your problem, collect this information before asking for help:

# OS and kernel
uname -a
cat /etc/os-release

# Python version
python3 --version

# ryzen_smu version
cat /sys/kernel/ryzen_smu_drv/drv_version 2>/dev/null || echo "not loaded"

# CPU info
sudo dmidecode -t processor | grep -E "Version|Signature|Family|Model|Manufacturer"

# Daemon logs
journalctl -u uxtu4linux.service -n 50 --no-pager

# App config
cat /opt/uxtu4linux/src/Assets/config.ini

Open an issue on GitHub with this output and a description of what you were doing when the problem occurred.

Report an issue · Releases

Home

Getting started

Using the app

Internals

Clone this wiki locally