Blank or Broken Preview on Wayland? Fix ScanTailor Advanced Rendering

The Symptom

• The main window opens, but the page preview area stays blank or renders incorrectly.
• Dialogs and panels paint broken or flicker.
• Everything works when you log into an X11 session instead.

The Cause

ScanTailor Advanced’s Linux builds are Qt5 builds. As the project README explains (issue #97), on a Wayland session the native Wayland platform plugin can produce broken dialogs and painting. That is why the application ships with an automatic fallback: if it detects a Wayland session (XDG_SESSION_TYPE=wayland) and you have not set QT_QPA_PLATFORM yourself, it defaults to the X11 (xcb) platform plugin, which renders correctly through XWayland. Release v1.2.1 formalized this Wayland rendering fix, alongside a fix for thumbnail context menus on multi-monitor setups.

If you are on an older build, or an environment variable is overriding the fallback, you get the broken native-Wayland rendering instead.

The Fix, Step by Step

1. Update to v1.2.1 first

Get the current Linux build — AppImage or .deb — from the download page. v1.2.1 is the release that addresses Wayland rendering, so an older build is the first thing to rule out.

2. Let the XCB fallback do its job

On v1.2.1, simply start the program in your Wayland session without setting QT_QPA_PLATFORM. With that variable unset, the app detects the Wayland session and uses the X11/xcb plugin automatically. If you previously exported QT_QPA_PLATFORM=wayland in your shell profile or a launcher file, remove it and try again.

3. Force XCB manually if needed

To pin the X11 plugin explicitly, start the program with:

QT_QPA_PLATFORM=xcb ./scantailor-advanced

(Adjust the executable path for the AppImage or the installed scantailor-advanced binary.)

4. Only if you specifically want native Wayland

The fallback can be switched off: setting SCANTAILOR_NO_XCB_FALLBACK=1 keeps native Wayland rendering, and you can also set QT_QPA_PLATFORM=wayland yourself. Do this only for testing — if the preview breaks again, you have confirmed the cause, and step 3 is your fix.

Prevention

• Stay on the current release: platform fixes land in new versions, and v1.2.1 is the Wayland fix release.
• Do not set QT_QPA_PLATFORM globally for all Qt apps unless you know an app needs it — a global value silently overrides ScanTailor’s own fallback logic.
• If you maintain a custom launcher or .desktop file, check it for stale environment settings after upgrading.

Other platforms and problems: see the troubleshooting archive.

FAQ

Does the XCB fallback mean the app runs slower on Wayland?

It runs through XWayland with the X11 plugin, which is the configuration the project itself chooses by default on Wayland sessions precisely because it renders correctly. For a page-processing tool, correct previews matter more than the native-plugin difference.

I set SCANTAILOR_NO_XCB_FALLBACK=1 and the preview broke again. Now what?

That confirms native Wayland rendering is the problem on your system. Remove the variable (or set QT_QPA_PLATFORM=xcb) and the fallback behavior returns.

Is this a Windows or macOS issue too?

No. This is specific to Linux Wayland sessions. Windows start-up problems are a different checklist — see ScanTailor Advanced won’t open.