Troubleshooting

Known problems and edge cases, by symptom: what you see, why it happens, and what to do. Every fix here is something you can run as-is. For a full record of how each one was found, follow the link to its CHANGELOG.md entry.

Start here, whatever the problem:

vayu-verify                        # does this machine still match the repo? lists anything that differs
journalctl -b -1 -p 0..3 --no-pager  # errors from the previous boot (the one that went wrong)
journalctl -b -p 0..3 --no-pager     # errors from this boot

Most “it stopped working after an update” cases are a differs: line in vayu-verify: the repo changed but the root-owned part wasn’t re-applied. The update notification says which script to run. If you missed it:

~/dotfiles/system/apply.sh    # files under / (sysctl, systemd drop-ins, PAM, ...)
~/dotfiles/splash/apply.sh    # boot/shutdown splash
~/dotfiles/greeter/apply.sh   # login screen
~/dotfiles/install.sh         # everything, including new packages; safe to re-run

Escape hatches worth knowing before you need them:

SysRq needs kernel.sysrq = 176 (system/etc/sysctl.d/99-sysrq.conf, installed by system/apply.sh). Check with sysctl kernel.sysrq. Press the letters about a second apart, holding Alt+PrtSc the whole time. On keyboards where PrtSc needs Fn, hold Fn too.

Shutdown: the logo stays up and the machine doesn’t turn off

Why: a service is taking long to stop. systemd waits up to 90 s per service (DefaultTimeoutStopSec), then kills it. If shutdown as a whole is stuck, systemd forces the reboot/power-off after 30 min (JobTimeoutAction=reboot-force on reboot.target). The logo hides the countdown.

What to do:

1. Press Esc. A line like A stop job is running for <service> (1min 2s / 1min 30s) names the service.
2. Wait for it (at most 90 s per service), or use SysRq S U B (see above) to reboot now without losing written data.

3. After the next boot, see what held it up:

   journalctl -b -1 -e --no-pager | grep -E 'stop job|Timed out|Killing'
   

4. If the same service does it every time, cap its stop timeout (replace NAME):

   sudo systemctl edit NAME.service
   # add, between the comment lines:
   # [Service]
   # TimeoutStopSec=10s
   

The splash itself adds at most 2.6 s (vayu-splash-hold.service, so the intro can finish) and can’t hang: it’s a sleep 2.6, and it’s skipped when Plymouth isn’t running.

Shutdown: the screen goes black but the machine stays on

Why: the last step of shutdown (unmounting, then the kernel switching the hardware off) is stuck, usually in a driver or firmware. On this setup that step is invisible on purpose: vayu-splash-blank.shutdown turns the console black on black so no text shows after the logo. It also has no automatic reset: RebootWatchdogSec=0 (see the next section) stopped the hardware watchdog from rebooting a machine stuck there after 10 min.

What to do:

1. Hold Alt+PrtSc and press S, U, then O (power off) or B (reboot), a second apart.
2. If that does nothing, hold the power button for ~10 s.

3. If it happens more than once, look at what the last step prints. Do this once, then restore:

   # 1. let the final text show: disable the blanking hook...
   sudo chmod -x /usr/lib/systemd/system-shutdown/vayu-splash-blank.shutdown
   # ...and drop quiet/loglevel from the kernel command line
   sudo sed -i -E 's/ (quiet|loglevel=3)\b//g' /etc/kernel/cmdline && sudo mkinitcpio -P
   # 2. reboot and read (or photograph) the screen at the end of shutdown
   # 3. restore both: apply.sh re-adds the options and re-enables the hook
   ~/dotfiles/splash/apply.sh
   

   Look for the last lines before it stops (often a driver name or INFO: task ... blocked).

Shutdown: I want the automatic 10-minute reset back

For an unattended machine (no one to press SysRq), you may prefer the watchdog over a clean screen. Remove the drop-in and re-execute systemd:

sudo rm /etc/systemd/system.conf.d/no-reboot-watchdog.conf
sudo systemctl daemon-reexec
systemctl show -p RebootWatchdogUSec   # 10min = watchdog armed again

The cost: the kernel line watchdog: watchdog0: watchdog did not stop! shows after the shutdown logo again (next section). system/apply.sh reinstalls the drop-in, and vayu-verify reports it as missing. To keep it removed, also delete ~/dotfiles/system/etc/systemd/system.conf.d/no-reboot-watchdog.conf in your copy of the repo.

Shutdown: text appears after the shutdown logo

What should happen: reboot shows the logo, then black, then the firmware logo. Power-off shows the logo, then the machine turns off. What the text looks like tells you which part is missing:

Background: the changelog entries no text after the shutdown logo and no watchdog line after the shutdown logo.

Boot: the firmware logo stays up for ~15 s

Expected on AMD Raven-family laptops (the Acer this was built on), not a hang. Loading the amdgpu driver costs ~6 s of CPU however it’s loaded, and that time comes before the Vayu logo can appear. Measured and explained in splash/README.md (“Why the boot is ordered this way”). Only building amdgpu into a custom kernel would remove it.

Boot: stuck on the Vayu logo

The light keeps running along the wind line until the login screen starts, so a logo that keeps animating means the login screen hasn’t started.

1. Press Esc to see the boot log. The last lines say what it’s waiting for.

2. Ctrl+Alt+F2, log in, and check the login screen service:

   systemctl status greetd
   journalctl -b -u greetd --no-pager | tail -30
   

3. If the login screen itself is broken, the rollback in greeter/README.md puts back stock tuigreet from that tty2 login.

The splash can’t stop a boot by itself: if Plymouth or the theme fails, boot carries on in text mode.

Boot: text instead of the Vayu logo

~/dotfiles/splash/apply.sh --check   # lists anything missing
cat /proc/cmdline                    # needs: quiet splash loglevel=3 rd.udev.log_level=3 plymouth.use-simpledrm

~/dotfiles/splash/apply.sh fixes whatever --check lists and rebuilds the UKI. On a machine without /etc/kernel/cmdline (not a UKI setup) it can’t edit the command line and says so: add those options in your boot loader instead.

To remove the splash completely, follow “Rollback” in splash/README.md.

Boot: a blank screen for a few seconds before the logo

The vayu-kms early-graphics hook is only installed on AMD Raven-family APUs; on every other GPU system/apply.sh keeps the stock kms hook in /etc/mkinitcpio.conf (and puts it back if an older version removed it), so the driver loads from the initramfs. If you still see this, check grep ^HOOKS /etc/mkinitcpio.conf lists kms, then run system/apply.sh and reboot. Without it Plymouth draws on the firmware framebuffer (plymouth.use-simpledrm) until the real driver loads, which shows as a blank screen or one flicker.

Install: mpd or ydotool failed on a fresh machine

Both were fixed in the installer (CHANGELOG 2026-10-16); re-run install.sh to pick that up. mpd failed with “Failed to access ~/Music: No such file or directory”: its directories didn’t exist yet, and mpd.service.d/prepare-dirs.conf now creates the ones mpd.conf names. ydotool failed with “failed to open uinput device: Permission denied”: the input group and ydotool’s udev rule only take effect after a re-login/reboot, so the installer now grants your user an ACL on /dev/uinput for the current boot. If either still fails: systemctl --user status mpd ydotool and getfacl /dev/uinput.

Hardware: a different laptop than the one this was built on

Hardware-specific parts are detected, not hardcoded: packages/hardware.sh picks microcode (intel-ucode/amd-ucode) and GPU drivers (vulkan-intel + intel-media-driver, vulkan-radeon, vulkan-nouveau) from /proc/cpuinfo and the PCI display controllers; the lid device (/proc/acpi/button/lid/*), AC adapter (power_supply type=Mains), battery and backlight are found at runtime. To see what this machine gets: source ~/dotfiles/packages/hardware.sh; hw_packages. Still tied to the original hardware: hibernate stays masked (it broke amdgpu resume there), and the greeter layout assumes a 1920x1080 panel (160x45 console).

Hotspot: devices join but nothing loads

The hotspot (vayu-hotspot on, the Wi-Fi menu, or the teal capsule) shares this laptop’s internet. Devices that connect but can’t open anything are almost always being dropped by the firewall: Docker and ufw set the FORWARD chain to DROP, and the hook that lets hotspot traffic through isn’t installed. Install it and restart the hotspot:

~/dotfiles/system/apply.sh        # installs /etc/NetworkManager/dispatcher.d/50-vayu-hotspot
vayu-hotspot off && vayu-hotspot on
sudo iptables -S FORWARD | grep vayu-hotspot   # two ACCEPT rules while it's on

Also check vayu-hotspot status shows an internet source: the hotspot shares a wired connection or a USB-tethered phone, not Wi-Fi (next section). See the 2026-10-19 hotspot entry in CHANGELOG.md.

Hotspot: my Wi-Fi disconnected when I started it

By design. NetworkManager can’t keep this Wi-Fi card connected to a network while it hosts one (most laptop cards can’t, or only on the same channel), so the hotspot takes the Wi-Fi card over and shares the wired connection instead. vayu-hotspot on warns before it drops Wi-Fi. vayu-hotspot off gives the card back; NetworkManager then reconnects to your saved network by itself.

Hotspot: my phone doesn’t see it, or it won’t start

• Not in the phone’s list: the hotspot uses channel 6 (2.4 GHz), which every country allows. If you set another one, go back to it: vayu-hotspot on --channel 6.
• “couldn’t start it on 5 GHz”: many cards’ firmware refuses to host on 5 GHz until it has seen a 5 GHz network nearby. Use --band bg.
• “can’t be an access point”: this laptop’s Wi-Fi card doesn’t support hosting at all (iw list has no AP under “Supported interface modes”). A USB Wi-Fi adapter that does works: vayu-hotspot on --device <its name>.
• “needs dnsmasq”: sudo pacman -S dnsmasq (install.sh installs it on new machines).

Panels: a key (Super+D, Super+Shift+W…) or a bar click opens nothing

Every launcher and panel is a Vyom tool, each its own repo. See what Vyom has loaded and why anything is skipped:

vyom list                                  # every tool: ok, or what it needs
tail -20 ~/.local/state/vyom/daemon.log    # errors from the panels

• vyom: command not found, or a tool missing from the list: a machine set up before Vyom (or before a tool was added) doesn’t have it yet. ~/dotfiles/install.sh (safe to re-run) clones Vyom and every tool in VYOM_TOOLS and updates the ones already there.
• “needs X”: install X (vyom list names it), then vyom reload.
• Nothing at all, even vyom dvara in a terminal: Vyom needs gtk4-layer-shell and python-gobject (install.sh installs both). Restart it with vyom quit; vyom daemon.
• The panel shows but looks like a flat box: SwayFX’s blur behind it comes from layer_effects "vyom" in sway’s config; reload sway.

Login: the desktop doesn’t start after logging in

The screen returns to the login prompt or goes black. Sway’s own log goes to the journal (not the screen):

journalctl -b -t sway --no-pager | tail -40

Run it from a Ctrl+Alt+F2 login. A config error shows with a line number; sway --validate checks the config without starting it.

Login: wrong colours or font on the login screen

The red box border or the rounded console font missing means vt-palette.service or the console font isn’t in place:

~/dotfiles/greeter/apply.sh
systemctl status vt-palette.service

Suspend: the screen goes black on the lock screen after opening the lid

Known, unresolved, rare. Seen once: after a quick lid close/open, the lock screen showed, then went black a few seconds later while typing the password, and came back on its own. Nothing was logged.

What to do: wait a few seconds. If it doesn’t come back, use SysRq S U B rather than the power button. Then save what was logged and open an issue:

journalctl -b -1 --since "-10 min" --no-pager > ~/lid-black-screen.log

Details: Lid-close, suspend vs hibernate in docs/ARCHITECTURE.md.

Suspend: the laptop powered off with the lid closed

By design: after 30 min continuously closed, the laptop powers off instead of staying suspended. Hibernate is removed on purpose (it corrupted the amdgpu firmware reload). Change the delay, or test it safely, in /etc/lid-timeout-poweroff.conf (repo copy: system/etc/lid-timeout-poweroff.conf):

TIMEOUT_SECONDS=1800   # seconds the lid must stay closed
DRY_RUN=1              # notify instead of powering off (testing)

Install: a step failed

install.sh doesn’t stop at a failing step. The summary at the end prints a fix: line under each one. Then:

grep -n 'command failed' ~/.local/state/vayu/install-logs/latest.log   # the exact failing command
less +G ~/.local/state/vayu/install-logs/latest.log                     # diagnostics are at the end

Fix the cause and run install.sh again: it skips what’s already done. Fallbacks keep the desktop usable: stock sway if swayfx won’t build, yay-bin if yay won’t, stock tuigreet if the patched login screen won’t. The full list of what install needs first is in the README.

AI tools: the approval window doesn’t appear

The agent got "status": "error" back, or it’s waiting and nothing shows.

~/.local/share/anumati/install.sh --check         # installed? (run it without --check to install)
journalctl --user -u 'anumati-*' -n 30 --no-pager   # the window's own errors
echo "$WAYLAND_DISPLAY"                           # the agent must run inside your desktop session

The window needs your Wayland session: an agent running over SSH or in a container without XDG_RUNTIME_DIR can’t open it (the error says “no Wayland session found”). If notifications are in Do Not Disturb you won’t get the “Root access requested” popup, but the window still opens on the current workspace.

AI tools: a command hung or failed only under anumati

Commands run as root with no input and no terminal, from /, with root’s environment. So:

• anything that asks a question waits until its 30-minute limit: use --noconfirm, -y, -f;
• ~ means /root, not your home: write /home/<user>/...;
• relative paths are relative to /.

The full output is in the result the agent got, and every run is logged: sudo tail /var/log/anumati.log | jq ..

AI tools: I approved by mistake, or want to see what ran

Everything that ran as root is in /var/log/anumati.log (one JSON line per command, with its exit code), and every request, including denied ones, in ~/.local/state/anumati/requests.jsonl. There’s no undo: reverse it by hand (e.g. pacman -R, systemctl disable). To stop agents using the tool: ~/.local/share/anumati/install.sh --uninstall. (anumati was called vayu-elevate before 2026-10-21; that name is now a link to it.)

Keys: I don’t know (or forgot) a keybinding

Super+Shift+/ searches every keybinding on the system (sway, tmux, kitty, zed, nāda, the Vyom panels, popups, and the SysRq combos above). In tmux, prefix ? lists tmux’s keys and runs the one you pick. Search action then object: “kill window”, “reboot hung”.

Reporting a problem

Include the output of these, from the boot where it happened if you can:

vayu-verify
git -C ~/dotfiles describe --tags --always   # which version you're on
journalctl -b -1 -p 0..4 --no-pager          # previous boot; -b for this one

Open an issue at github.com/Theyashsawarkar/vayu/issues.

Tools: updating or reinstalling Vayu’s tools (kosha)

Vayu’s own tools (the Vyom panels and their tools, nāda, anumati, sangam) are installed by kosha. At login a notification offers “Update now” when any has a new release.

kosha list --installed     # versions, and what has an update
kosha update               # update everything (prints what changed)
kosha doctor               # missing programs, broken links, local changes
kosha install nada@0.1.0   # go back to (and pin) an older release; kosha unpin nada later

“has local changes” means a tool’s folder was edited: commit or stash the change there, or kosha update --force (stashes it). anumati’s update runs its installer, which asks for your password: run it in a terminal.