Troubleshooting

Troubleshooting

No tray icon appears when I launch stepshot

Almost always: stepshot started but exited immediately because it found no input device (you are not effectively in the input group). Launched from the menu there's no terminal, so you see nothing.

Fix: add yourself to the input group and reboot (not just re-login) — see Requirements and Permissions. Since alpha.2, stepshot stays in the tray and shows a "no input device" notification instead of vanishing silently, which makes this case easier to spot.

To see the actual error, run it from a terminal:

stepshot
# e.g. "click capture unavailable: no pointing device ... Is the user in the `input` group?"

The tray icon shows, but recordings have 0 steps

The app is running but clicks aren't being captured — same root cause as above. The most common trap: you added the input group and only logged out/in. The systemd --user manager survives logout and keeps its old groups, so menu-launched stepshot still lacks input.

Fix: reboot (or loginctl terminate-user "$USER"). See Requirements and Permissions.

org.kde.KWin.ScreenShot2.Error.NoAuthorized: The process is not authorized

KWin refused the screenshot. Causes:

• You started stepshot via newgrp input / sg input. The group switch makes the process non-dumpable (e.g. Fedora's suid_dumpable=2), so KWin can't read /proc/<pid>/exe to authorize it. Reboot and launch normally instead.
• The .desktop file is missing or its Exec= doesn't match the binary. Re-run ./install.sh. KWin matches the running executable's resolved path against Exec=, so the binary must be the copied one at ~/.local/bin/stepshot (not a symlink, not run from a build directory). See Requirements and Permissions.

A step screenshot is blank / empty

This happens when the click's "active window" has no visible content — KDE's transparent Xwayland video bridge, or the bare desktop. Since alpha.2, stepshot detects this and falls back to capturing the whole monitor under the cursor (wallpaper, panel and all). If you still get a blank image, make sure you're on alpha.2 or newer.

The screenshot is the wrong monitor / the panel is missing

Fixed in alpha.2: the full-screen fallback now captures the monitor under the cursor (where you clicked), not the monitor of the active window. Update if you see this on an older build.

Some steps are a full screen instead of one window

Expected since alpha.3: clicks that don't land in the active window (panel, start menu, desktop) and clicks inside popup menus (context menus, dropdowns) capture the whole monitor under the cursor — a window capture simply wouldn't show what you clicked. Such steps say "(full-screen view)" in the description.

Descriptions say “in window …” instead of naming the button

The clicked app isn't exposing element names over accessibility (AT-SPI). This is expected for some apps; see Requirements and Permissions → Accessibility:

• Qt/KDE apps need Qt's accessibility bridge.
• Chrome / Electron need --force-renderer-accessibility.
• Games / canvas apps expose nothing — the window-level description is the best available.

Nothing happens / "session D-Bus unreachable"

stepshot needs a running KDE Plasma / Wayland session (KWin). It does not work on GNOME, plain X11 without KWin, or over a plain SSH shell without the session's D-Bus/Wayland environment.

Getting more detail

STEPSHOT_DEBUG=1 STEPSHOT_ONESHOT=1 stepshot

This captures a single step right now and prints diagnostics (cursor info, ScreenShot2 result keys, the resolved description) to stderr.