carrotwm
contents

Troubleshooting#

First stop: the logs#

carrot prints to stderr, which lands in the journal under a display manager (journalctl --user -b and search for carrot) or your terminal from a TTY. If a session crashed, the story is already written down: every panic produces a numbered ~/.cache/carrot/carrotCrashLogN.log with the message, a backtrace, and the last 256 KB of stderr. Grab the highest number.

Stuck session#

Ctrl+Alt+F2 (or any F-key) always switches VTs; it is hardcoded and cannot be broken by config. From another VT, burrow quit asks for a graceful shutdown, and plain kill <pid> does the same thing via SIGTERM.

carrot exits immediately#

  • A config error is never the cause. A file that fails to parse prints every error and boots on the built-in default, and a broken burrow reload keeps the running config. Still worth checking the log for carrot: config: lines to see what needs fixing, and carrot check-config parses your config from any TTY without starting a session.
  • No Vulkan driver found: carrot looks at VK_ICD_FILENAMES, then /run/opengl-driver/share/vulkan/icd.d, /usr/share/vulkan/icd.d, /etc/vulkan/icd.d. Install your GPU's Vulkan driver, or point VK_ICD_FILENAMES at its manifest. carrot render-probe tests this path alone, and carrot doctor walks the whole GPU bring-up and writes a report file worth attaching to any bug.
  • taproot libc missing: the error says to set CARROT_LIBC. The GPU driver needs taproot's libc.so.6/libm.so.6, searched next to the binary, then in ../lib/carrot, then via CARROT_LIBC/CARROT_LIBM. Every install channel stages the pair (carrot install writes them into PREFIX/lib/carrot); see Installation.
  • Keymap error: a configured non-default layout needs xkeyboard-config, so set XKB_CONFIG_ROOT to its data directory. The default US layout needs nothing on disk.

Carrot is missing from the login screen#

The session entry lives at PREFIX/share/wayland-sessions/carrot.desktop. Distro packages use /usr and always show up; a source install defaults to /usr/local, which some display managers do not scan. Re-run with sudo carrot install --prefix /usr and it appears.

Black screen or wrong output behavior#

carrot drm-probe dumps what the kernel reports: connectors, modes, planes. carrot spike-scanout runs a standalone scanout test from a TTY. Compare the log against these.

A window renders wrong#

burrow dump-shadow writes the focused window's committed pixels (carrot's CPU-side copy) to /tmp/carrot-shadow-<id>.ppm. If the PPM looks right but the screen is wrong, it is carrot's render path; if the PPM is wrong, the client committed those pixels. Say hi in Discord with both.

burrow says no socket found#

burrow needs XDG_RUNTIME_DIR and looks for carrot.$WAYLAND_DISPLAY.sock. Outside the session (say, over SSH), export both variables, or check ls $XDG_RUNTIME_DIR/carrot.*.sock.

Screen sharing does not start#

With no picker configured, carrot waits for a pointer click to choose the cast source; that pause is the consent dialog. A configured picker that hangs is killed after a timeout and the request cancelled cleanly. carrot portal-probe runs the portal backend standalone for testing, and carrot pw-probe checks the PipeWire connection.

Probes, all of them#

Every diagnostic subcommand is listed in Running carrot.