Troubleshooting
Unknown Hyprexpo Config Keys After an Upgrade
Errors such as unknown config key 'plugin.hyprexpo.label_enable' can mean that Hyprexpo did not load, so its options have not been registered. Check the loader and loaded plugins before removing existing settings:
command -v hyprpm
hyprctl plugin listOn Arch Linux, hyprpm is now a separate package. If the command is missing after upgrading Hyprland, install it with sudo pacman -S hyprpm. Then follow the post-upgrade rebuild and reload steps in the updated Hyprland session. Keep the existing plugin registration and valid config keys; a config reload alone does not rebuild an incompatible plugin.
hyprpm Cannot Check Out the Running Hyprland Commit
If an update reports Could not checkout the running Hyprland commit, retry with the full repository history:
hyprpm --no-shallow updateWait for any other updater to finish first. Run this as your normal user in a terminal so you can authenticate the header-installation prompt. Once the update succeeds, run hyprpm reload and hyprctl reload, then check hyprctl plugin list and hyprctl configerrors again. The --no-shallow retry is only needed for this checkout failure; it does not repair an unavailable saved plugin revision, which is covered below.
hyprpm Cannot Check Out a Saved Revision
If hyprpm update prints Plugin has revision set, resetting followed by Could not parse object, inspect repository.rev in /var/cache/hyprpm/$USER/hyprexpo/state.toml. An explicit revision overrides the repository's compatibility pins. A PR commit can disappear from normal clones after a squash merge and deletion of its temporary branch; retaining the object in a developer checkout does not make the installation updateable.
From a source checkout, run make check-hyprpm-state. The check makes no changes. It accepts unpinned state offline, and verifies explicit revisions using a fresh clone. Failed network access also refuses replacement instead of assuming the revision is safe. It cannot establish ABI compatibility or guarantee that an upstream maintainer will preserve the accepted refs in the future.
To restore normal pin selection on a supported released Hyprland, first back up the installed state and binary, then re-register without a revision:
backup_root="${XDG_STATE_HOME:-$HOME/.local/state}/hyprexpo"
mkdir -p "$backup_root" &&
backup_dir="$(mktemp -d "$backup_root/revision-recovery.XXXXXX")" &&
cp -a "/var/cache/hyprpm/$USER/hyprexpo" "$backup_dir/" &&
hyprpm remove hyprexpo &&
./scripts/hyprpm-add.sh https://github.com/sandwichfarm/hyprexpo &&
hyprpm enable hyprexpo &&
hyprpm reload &&
hyprctl reloadKeep the backup until loading succeeds. Run hyprpm as your normal user and authenticate its sudo prompt in your terminal. If a command fails, stop and retain the output and backup. Do not delete the entire cache or replace rev with another temporary PR hash. Development-track installations must retain their matching compositor and use the development recovery procedure.
Verify hyprctl version, hyprctl plugin list, and hyprctl configerrors after recovery. A failed install can unload the plugin and cause unknown config key 'plugin.hyprexpo.…' errors until it is loaded again. Finish loading and reload the config before treating these as removed options.
Plugin Load Fails With API or Hash Mismatch
Rebuild HyprExpo against the same Hyprland revision that is running, then load the rebuilt plugin explicitly and reload the config:
hyprctl plugin load /var/cache/hyprpm/$USER/hyprexpo/hyprexpo.so # hyprpm install
hyprctl plugin load ~/.local/lib/hyprland-plugins/hyprexpo.so # local install
hyprctl reloadA plain hyprctl reload does not retry a config-declared load that already failed earlier in the session. Hyprland only re-attempts config-managed plugin loads when the declared plugin list changes, so a failed attempt stays sticky until the next session. Loading the rebuilt plugin manually clears the failure immediately, and the following hyprctl reload applies the plugin options and binds again.
Plugin Load Fails Because Dependencies Are Missing
Install the build dependencies and rebuild. Current linked runtime dependencies include Lua 5.5, pangocairo, and xkbcommon. The Lua ABI must match Hyprland: having Lua 5.4 development files installed is not sufficient for the current Hyprland 0.57 target. See Lua module selection if your distribution uses a versioned pkg-config module.
Invalid Config Values
Invalid workspace_method or border color values should be logged and fall back safely. Use the documented formats in configuration options and multi-monitor layouts.
Columns Outside the Supported Range
columns is clamped to 1..7 so pointer and keyboard selection stay in bounds.
Replacing a Loaded Plugin Crashes Hyprland
For development, prefer ./scripts/run-nested.sh or make dev-reload so Hyprland loads a fresh user-owned build by absolute path. If you intentionally replace an installed plugin file, use make install or install instead of overwriting the file with cp.
Per-Monitor Placement Does Not Apply
Check the monitor name from Hyprland and use comma-separated entries such as:
plugin {
hyprexpo {
workspace_method = DP-1 first 1, HDMI-1 center 5, center current
}
}