Diagnosing Qt Queued Signal-Slot Connection Failures Across Threads

Recognizable condition

You emit a signal with Qt::QueuedConnection (or let Qt choose queued because objects live in different threads) but the corresponding slot in the receiver object is never invoked. The program shows no error, and the signal‑emit call returns immediately.

Cause and diagnostic indicators

Possible cause	What to look for
Missing Q_OBJECT macro in the receiver class	Compiler does not generate meta‑object code; connection fails silently at runtime.
Receiver object lives in a thread without an event loop	Queued delivery relies on the target thread’s event loop; if QThread::exec() is not running, events are dropped.
Object created in the wrong thread (affinity mismatch)	QObject::thread() returns a thread different from the one you expect for the slot.
Auto‑connection via QMetaObject::connectSlotsByName mis‑named slot	Slot name does not follow on__ pattern; connection is not made.
Blocking or long‑running code in the receiver thread’s event loop	Calls like QThread::msleep or a tight loop prevent the event loop from processing queued events, making the slot appear never called.

Ordered diagnostic checks

1. Verify the receiver class contains the Q_OBJECT macro. Look at the class definition; if missing, add it and re‑run qmake or CMake to regenerate the moc file.
2. Confirm the receiver object has an event loop. In the thread that owns the object, ensure you call QThread::exec() (or start the thread with QThread::start which defaults to an event loop). You can check by printing QThread::currentThreadId() inside the slot and verifying it runs.
3. Check thread affinity: after creating the receiver, call qDebug() << receiver->thread(); and compare with the thread you intend to run the slot in. If they differ, move the object with receiver->moveToThread(targetThread) before making the connection.
4. Inspect the connection type used. When you call connect, explicitly pass Qt::QueuedConnection and verify the return value is a valid QMetaObject::Connection (not 0).
5. If you rely on connectSlotsByName, ensure the slot follows the naming convention on__. Rename either the object or the slot accordingly.
6. Look for blocking calls in the receiver thread’s event loop. Replace any QThread::msleep or while (!condition) {} with timers or asynchronous checks, or move the blocking work to a worker thread.

Fixes tied to findings

• Add Q_OBJECT: Insert Q_OBJECT in the private section of the class, rerun the meta‑object compiler, and rebuild.
• Start event loop: Ensure the thread runs exec(); for a QThread subclass, do not override run() without calling the base implementation, or post work via QMetaObject::invokeMethod.
• Correct thread affinity: After creating the receiver, call receiver->moveToThread(&targetThread) before establishing the queued connection.
• Fix auto‑connection names: Rename the slot to match on__ or connect manually with connect.
• Eliminate blocking code: Replace blocking sleeps with QTimer::singleShot or move the work to a separate QRunnable managed by a QThreadPool.

Escalation criteria

If after performing the checks above the slot still does not invoke:

• Enable Qt debug output by setting the environment variable QT_DEBUG_PLUGINS=1 or QT_LOGGING_RULES=qt.*=true to see connection warnings.
• Try a direct connection (Qt::DirectConnection) as a test; if the slot runs, the problem is definitely queued‑delivery related (event loop or thread affinity).
• Consider using QMetaObject::invokeMethod with Qt::QueuedConnection as a lower‑level alternative to verify whether the issue lies in the connect call itself.
• Check the Qt version; starting with Qt 5.15, queued connection handling for movable types changed. If you are passing custom types by value, ensure they are registered with qRegisterMetaType and have a copy constructor.

When the problem persists, isolate the code into a minimal reproducible example (two threads, one emitter, one receiver) and verify each step in that testbed before reintegrating into the larger application.