Troubleshooting

Common problems and their answers. If what you see isn't here, the section on bug reports at the bottom explains how to collect the logs that make a fix possible.

4-finger gestures act like 3-finger ones

By design: anything left unbound falls back to the 3-finger behavior. An unbound tap-more runs the regular tap action, an unbound swipe-more-up/down drives the animated workspace carousel, and an unbound swipe-more-left/right keeps the horizontal drag (resize or move-view). The actions are not compiled in; they come from the config file, which is the point of shipping one.

Add the binds inside your touchscreen-swipe block (they apply live on save, no re-login needed):

tap-more        { toggle-overview; }
swipe-more-down { close-window; }
swipe-more-up   { fullscreen-window; }

config/gestures.kdl ships all of them. Background: issue #2.

Upgrading from v26.04.18 or earlier? The old tap-4/swipe-4-* names now fail validation with "unexpected node": rename them as above (EasySetup does it for you on its next save, and update-niri-tablet.sh offers to do it right after installing), and check that fingers is 3 or 4.

pacman offers to replace niri on -Syu

The IgnorePkg = niri pin is missing from /etc/pacman.conf. Answer N to pacman's question, add the pin:

IgnorePkg = niri

and update via ./update-niri-tablet.sh instead (Updating). The updater re-checks the pin on every run.

niri validate rejects gestures {}

The binary doing the validating is stock niri. Either the package isn't installed (check with pacman -Q niri niri-tablet) or another niri is shadowing it on PATH:

which -a niri
niri --version     # patched prints: 26.04 (v26.04-modified)

A running session also keeps its old binary: log out and back in after installing or updating.

A 3-finger swipe pinch-zooms or scroll-drags an app

Gesture ownership should prevent exactly this: from the moment touchscreen-swipe.fingers fingers are down, the compositor owns the whole sequence and apps never see it. It landed in patches 0010/0011, so first make sure you're on a current release. If it still happens on the latest release, that's a bug worth reporting: enable debug-log, reproduce, and file it with the log lines.

If instead you want an app to receive 3-finger touches (some design tools use them), raise fingers to 4 in touchscreen-swipe.

Gestures stop working after unplugging/hotplugging a touch device

Fixed by patch 0012 (touch-device removal no longer wedges gesture state). Update to a current release; if it recurs there, report it with debug-log output covering the unplug.

An edge swipe fires when dragging a shell panel

Don't bind an edge covered by a swipe-driven shell surface (a pull-down notification panel along the top is the classic case): the bound gesture fires mid-drag. Unbind that edge, or move the panel. Unbound zones are inert, so simply deleting the binding is enough.

The OSK types the wrong letters

You have a non-US system layout and a single-group xkb config. Give the layout two groups ("pt,us", your layout first) and niri-osk.sh flips the active group on toggle: OSK and auto-rotation.

Auto-rotate does nothing

The helper needs a real accelerometer, exposed through iio-sensor-proxy. Check for one with monitor-sensor after starting iio-sensor-proxy.service. Many touch laptops have none; in that case skip the helper, nothing else depends on it.

On a 2-in-1, rotation is also off while the device is in laptop mode: that is the tablet-mode gate, not a fault (On-Screen-Keyboard-and-Auto-Rotation#2-in-1s-rotation-only-in-tablet-mode).

Bug reports

debug-log turns on per-event logging of the gesture stack: every finger down/up/motion with slot ids, positions and timestamps, the recognition decision (finger count, direction, hold vs quick), and the action dispatched. It applies live, from the next touch, and every line is prefixed gesture-debug:.

gestures {
    debug-log
}

Reproduce the misbehaving gesture, then collect the lines. Under systemd sessions (including NixOS):

journalctl --user -u niri.service --since -10m | grep gesture-debug

Running niri from a terminal instead? The lines go to its stderr.

A good report includes: the device, the release (niri --version), the exact gesture and what you expected vs what happened, and those log lines. A short screen recording helps too: show-touch-points "gestures" renders the finger dots in the compositor, so any capture shows them. Remove debug-log from the config afterwards.