Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A Qt app on Linux will not start: xcb platform plugin found but not loaded

Errorqt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.

Short answer

Qt found the xcb plugin file but the plugin could not load, almost always because a library it needs, such as libxcb-cursor0, is missing. Turn on QT_DEBUG_PLUGINS to see the missing library, install it, or start the app on another platform with QT_QPA_PLATFORM.

  • Applies to Qt 6, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the app with plugin diagnostics on. Qt then prints details for every plugin it tries to load, including why xcb failed.

    QT_DEBUG_PLUGINS=1 ./my-qt-app
  2. 2Match what you see, then jump to its fix

    1. 1The QT_DEBUG_PLUGINS output names a shared library it cannot find, for example a libxcb library.A library the xcb plugin depends on is not installedFix
    2. 2The app runs under another desktop session type than the plugin expects, or QT_QPA_PLATFORM is set to something unintended.Qt picked a platform plugin that does not suit the sessionFix

What does the error look like?

  • qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.

Cause 1 of 2

A library the xcb plugin depends on is not installed

1Check

Qt's Linux requirements table lists xcb-cursor0, packaged as libxcb-cursor0, among the platform dependencies for the xcb plugin. Check whether that package is installed.

dpkg -l libxcb-cursor0

2Fix

Install the package that provides the missing library. For xcb-cursor it is libxcb-cursor0 on Ubuntu.

sudo apt install libxcb-cursor0

3Verify

The app starts without the plugin message.

./my-qt-app

Confirmed by doc.qt.io

Did this fix it?

Cause 2 of 2

Qt picked a platform plugin that does not suit the session

1Check

Qt chooses a default platform plugin for the system, and the QT_QPA_PLATFORM variable or the -platform argument overrides it. A leftover export in a shell profile is enough to force xcb.

echo "$QT_QPA_PLATFORM"
echo "$XDG_SESSION_TYPE"

2Fix

Unset a wrong override, or give Qt an ordered list; it uses the first plugin that is available.

unset QT_QPA_PLATFORM
QT_QPA_PLATFORM="xcb;wayland" ./my-qt-app

3Verify

The app opens a window.

QT_QPA_PLATFORM=wayland ./my-qt-app

Confirmed by doc.qt.io

Did this fix it?

How do I stop it coming back?

  • Install the platform libraries from Qt's Linux requirements page on every build and runtime machine, including containers.
  • Keep QT_QPA_PLATFORM out of shell profiles; set it per run.
  • Run the app once with QT_DEBUG_PLUGINS=1 on a clean machine before shipping a release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.