Troubleshooting on XFCE

Home · Installation · User guide · Configuration · Platform support

Tessera is a client of your window manager: it asks Xfwm4 to move, resize and focus windows, and it never replaces Xfwm4. Most problems on XFCE therefore fall into three groups: another program owns the key, the window manager or the application refused a request, or the configuration tells Tessera to leave the window alone. This page walks from symptom to cause.

Collect diagnostics first

Three headless commands cover most reports. None of them changes your session.

tessera --debug-info                              # session, backend, capabilities, config status
tessera debug windows --redact-window-titles      # one row per window Tessera can see
tessera debug windows --include-unmanaged --redact-window-titles   # also windows it ignores

--json switches --debug-info and the debug commands to JSON. tessera --debug-info --include-apps adds an application inventory. For a log, run tessera --autostart --log in a terminal (--log, -v and --verbose raise the level to debug; RUST_LOG overrides it), or journalctl --user -u tessera -e when the systemd user service runs it.

What --debug-info tells you

What tessera debug windows tells you

Columns are ID MANAGED UNMANAGED_REASON FLOATING CLASS INSTANCE FRAME TITLE. A window Tessera will not tile shows MANAGED false with one reason: non_tileable_type, modal or fixed_size. FLOATING true means a rule, a size threshold or your own toggle floats it.

Redact before sharing

Quick checklist

Run these in order; stop at the first one that fails.

echo "$XDG_SESSION_TYPE"                          # x11
xfwm4 --version                                   # Xfwm4 is installed
xprop -root _NET_SUPPORTING_WM_CHECK              # note the window id, then:
xprop -id <id-from-above> _NET_WM_NAME            # "Xfwm4"
pgrep -a tessera                                  # exactly one controller
xrandr --listmonitors                             # the monitors you expect
tessera --debug-info                              # config is "loaded", not invalid

Then press Alt+Shift+A (tall layout) and Alt+Shift+Z (re-evaluate all windows). If the windows tile, the problem was state; if not, find your symptom below.

Symptoms

A shortcut does nothing

Cause: another program already owns the combination, so Tessera leaves it alone, or the keyboard layout switcher consumes it.

Check

• Start Tessera with --log and look for shortcut collision: <chord> is already bound to <command> (an XFCE or Xfwm4 shortcut) or … is already taken by another application (an active grab by another X client).
• Preferences → Shortcuts flags the same collisions.
• List XFCE’s own bindings:

xfconf-query -c xfce4-keyboard-shortcuts -lv | grep -i alt

Fix — give one side up:

To move Tessera instead, change the modifier groups (option is Alt on Linux) or a single command in tessera.yml:

mod1: [option, shift]
mod2: [option, shift, control]

mod1 is Alt+Shift and mod2 is Alt+Shift+Ctrl by default. Edit them in Preferences → Shortcuts, or in the file, then reload.

Nothing is tiled

Cause: one of four states, listed from most to least common.

One application is never tiled

Check: tessera debug windows --include-unmanaged --redact-window-titles and find the row.

For rules, match against the CLASS or INSTANCE column of the same output.

A window is a few pixels off, or snaps back

Cause: the application’s size constraints (increments, minimum, maximum) override the requested frame, as with terminals that resize in character cells. Tessera accepts a size the window manager clamped and confirmed after one request; it re-requests an unconfirmed move at most twice before giving up.

Check

xprop -id "$(xdotool getactivewindow)" WM_NORMAL_HINTS _NET_FRAME_EXTENTS

Fix: float the application, or lower window-minimum-width / window-minimum-height. Reserve room with screen-padding-top|right|bottom|left and spacing with window-margin-size (window-margins toggles them).

Tessera reports “Could not place …”

Cause: Tessera ordered a frame or workspace move twice and the window system never showed it. Another placement tool, a script or the application itself is competing.

Check: Preferences → Diagnostics → Problems found lists the window id, class, attempts and whether Tessera gave up; the id matches tessera debug windows. Also run pgrep -a tessera and check that no other tiling helper is active.

Fix: stop the competing tool, or float the application. Use only one login-start method for Tessera.

The layout is wrong after plugging a monitor or changing workspace

Focus does not behave as expected

Focus does not follow the mouse. Tessera’s focus-follows-mouse (toggle Alt+Shift+Ctrl+X) is independent of Xfwm4’s focus model. Inspect Xfwm4’s side:

xfconf-query -c xfwm4 -p /general/click_to_focus
xfconf-query -c xfwm4 -p /general/focus_new
xfconf-query -c xfwm4 -p /general/prevent_focus_stealing

Xfwm4’s shipped defaults are click_to_focus=true, focus_new=true, prevent_focus_stealing=false, so new windows take focus. Use Settings → Window Manager Tweaks → Focus to change them.

The pointer jumps. That is mouse-follows-focus; set it to false or clear it in Preferences → Mouse.

Tiled windows show no focus border. With window-decorations: hide-tiled Xfwm4 draws no focus border on the bare window and Tessera draws none of its own. Set keep (Preferences → General → Window decorations) or use the focus shortcuts (Alt+Shift+J / K).

Title bars are missing after Tessera was killed

Cause: hide-tiled hides decorations; a clean exit (SIGTERM, SIGINT, Quit from the tray) restores them, a SIGKILL or crash does not. The original setting is stored on each window as _TESSERA_SAVED_MOTIF_WM_HINTS.

Fix: start Tessera once with window-decorations: keep; it restores every window. With hide-tiled it restores only floating ones.

Tessera does not start

Check service state with tessera service status.

The interface looks wrong

Tessera chooses its look from ui-style (auto by default) and the TESSERA_UI environment variable, which wins for one run. An unknown or unusable value falls back silently to auto; the reason is in the log and on the ui-provider-fallback line.

TESSERA_UI=gtk tessera --debug-info        # plain GTK, follows the desktop theme
TESSERA_UI=adwaita tessera --debug-info    # libadwaita 1.5+ if it can be loaded

Report a problem

Open an issue at https://github.com/fabioluciano/tessera/issues and include:

1. What you did and expected, and what happened instead, in a few lines.
2. Environment: distribution, XFCE version (xfce4-session --version), Xfwm4 version (xfwm4 --version), Tessera version (tessera --version) and how you installed it.
3. Diagnostics: the output of tessera --debug-info and tessera debug windows --include-unmanaged --redact-window-titles, or the text from Preferences → Diagnostics → Copy debug info.
4. Configuration: the relevant part of ~/.config/tessera/tessera.yml, trimmed and redacted.
5. Log: the lines around the failure from tessera --autostart --log, after you have read them for anything private.
6. Whether it is repeatable, and the exact keys pressed or windows involved.

If you cannot reproduce on an XFCE/X11 session with Xfwm4, say so: that is outside the tested profile. The source checkout also contains the real-session acceptance procedure at docs/testing/xfce-x11-smoke.md.