[Bug]: Matplotlib falls back to "headless" backend after a while in ssh -X session

[erjoalgo]

Bug summary

I reported this bug to QT developers: https://bugreports.qt.io/browse/PYSIDE-3025 but they believe it may be a usage error from the QT client, in this case matplotlib:

It really sounds like something completely unloads the QtWidgets module and Qt library and reloads them; which Qt does not support. Please get back to the matplotlib developers.

The error appears to happen after a while when working on a ssh -X session, and restarting the ssh -X session by logging out and back in temporarily resolves the issue.

The error I get after a while is:

ImportError: Cannot load backend 'QtAgg' which requires the 'qt' interactive framework, as 'headless' is currently running

In cbook.py matplotlib this is how matplotlib checks if qt is available:

QtWidgets = (
        sys.modules.get("PyQt6.QtWidgets")
        or sys.modules.get("PySide6.QtWidgets")
        or sys.modules.get("PyQt5.QtWidgets")
        or sys.modules.get("PySide2.QtWidgets")
    )

if QtWidgets and QtWidgets.QApplication.instance():
        return "qt"

In the error condition, QtWidgets.QApplication.instance() is falsey.

I'm not familiar with QT or matplotlib but I'd be happy to add more logging where relevant if it helps to track down this bug.

This is on debian bookworm, matplotlib 3.10.0 installed via conda.

Some qt-related versions:

pyqt                      5.15.10         py313h6a678d5_1  
pyqt5-sip                 12.13.0         py313h5eee18b_1  
pyqt6                     6.8.1                    pypi_0    pypi
pyqt6-qt6                 6.8.2                    pypi_0    pypi
pyqt6-sip                 13.10.0                  pypi_0    pypi
qt-main                   5.15.2              hb6262e9_12  

Code for reproduction

import matplotlib
matplotlib.use('QtAgg')
import matplotlib.pyplot as plt

...

plt.subplots()

Actual outcome

  File "/home/USER/git/6.86x/project1/sentiment_analysis/utils.py", line 102, in plot_toy_data
    plt.subplots()
    ~~~~~~~~~~~~^^
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 1777, in subplots
    fig = figure(**fig_kw)
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 1044, in figure
    manager = new_figure_manager(
        num, figsize=figsize, dpi=dpi,
        facecolor=facecolor, edgecolor=edgecolor, frameon=frameon,
        FigureClass=FigureClass, **kwargs)
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 553, in new_figure_manager
    _warn_if_gui_out_of_main_thread()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 530, in _warn_if_gui_out_of_main_thread
    canvas_class = cast(type[FigureCanvasBase], _get_backend_mod().FigureCanvas)
                                                ~~~~~~~~~~~~~~~~^^
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 369, in _get_backend_mod
    switch_backend(rcParams._get("backend"))
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/USER/anaconda3/envs/6.86x/lib/python3.13/site-packages/matplotlib/pyplot.py", line 435, in switch_backend
    raise ImportError(
    ...<2 lines>...
            newbackend, required_framework, current_framework))
ImportError: Cannot load backend 'QtAgg' which requires the 'qt' interactive framework, as 'headless' is currently running

Expected outcome

No error, plot is displayed.

Additional information

No response

Operating system

No response

Matplotlib Version

3.10.0

Matplotlib Backend

QtAgg

Python version

Python 3.13.2

Jupyter version

No response

Installation

conda

[timhoffm]

The error appears to happen after a while when working on a ssh -X session, and restarting the ssh -X session by logging out and back in temporarily resolves the issue.

Please put print(plt.get_backend()) somewhere in the ... of your example. It's a bit peculiar that the error happens only at plt.subplots() - specifically pyplot.py", line 369, in _get_backend_mod is only reachable if no backend is selected, but matplotlib.use('QtAgg') before should have done that.

For clarification: What are you doing exactly?

1. Start ssh -X session
2. Run your python script (it works) - what does print(plt.get_backend()) give?
3. Is the python session now closed or does it keep running?
4. wait
5. You retry the plot (it fails) - what does print(plt.get_backend()) give?

[erjoalgo]

1. Start ssh -X session

2. Run python script (it works) - what does print(plt.get_backend()) give?

It always gives QtAgg.

plt.get_backend(): QtAgg

The difference is actually that current framework is "headless" in the error case:

Error case:

DDEBUG pyplot.py n57x: value of current_framework: headless
DDEBUG pyplot.py fr4q: value of required_framework: qt

Normal case:

DDEBUG pyplot.py n57x: value of current_framework: None
DDEBUG pyplot.py fr4q: value of required_framework: qt

So it appears that _c_internal_utils.display_is_valid() returns False in the error case.

(I had mentioned that I thought it was the instance being None, but instance can be None in the normal case before any plots have been made.)

3. Is the python session now closed or does it keep running?
   The python script terminates but the ssh -X session continues running

4. wait

5. You retry the plot (it fails) - what does print(plt.get_backend()) give?Same as before, "QtAgg", I have matplotlib.use('QtAgg') after importing matplotlib. But now, _c_internal_utils.display_is_valid() is False.

cbook.py _get_running_interactive_framework:

if macosx and macosx.event_loop_is_running():
        return "macosx"
        _c_internal_utils.display_is_valid()))
    if not _c_internal_utils.display_is_valid():
        return "headless"
    return None

[tacaswell]

display_is_valid is reaching out to X11 or wayland to see if we can find a valid display manager.

The next test is when it is reporting no valid window manager you can run a hello-world Qt app and get it to work? Can you get any x11 program (xeyes?) when we are reporting 'headless'? That will determine if you are in a valid state that we are not correctly identifying as valid or something has gone on with your ssh/x session so that it is indeed invalid.

Can you provide the exact code you are using to test this?

---

As a side note, QtWidgets.instance() returns the QAppliaction instance for the process (there can be only one and you can not re-create it) if it exists otherwise None. This makes sense so you can always reach out to get the global instance, but you won't accidentally create the instance just by checking if it exists.

[erjoalgo]

Actually, you are right, I'm not able to run any X apps, so this is probably not a matplotlib issue:

$ xeyes 
Error: Can't open display: localhost:10.0

But I can run xeyes from a fresh ssh -X session.

I think this is not a matplotlib or QT issue, maybe an X11 forwarding issue, so I'm closing this bug. Thanks for your help.

[erjoalgo]

I found new relevant pointers to the likely root cause, which may be a defafult X11 forwarding timeout:

https://lists.apple.com/archives/x11-users/2013/Dec/msg00018.html

Re: X11 forwarding stops after a while

This works. Then (the next morning) I made some ssl certificates, and tried to
edit the configuration:
jarfx:/etc/apache2 # nedit /etc/sysconfig/apache2 &
[2] 14842
jarfx:/etc/apache2 # NEdit: Can't open display

jarfx:/etc/apache2 # exit
logout
[1]+ Exit 127 yast2
jar@jarfx:> xterm &
[1] 14922
jar@jarfx:> xterm: Xt error: Can't open display: localhost:10.0

This happens all the time after a sufficient delay. Exiting su and redoing su -
does not fix it. I have to log out and start a new session.

See the second answer here:
http://superuser.com/questions/407218/why-does-ssh-x-forwarding-timeout-after-a-while

Also see http://b.kl3in.com/2012/01/x11-display-forwarding-fails-after-some-time/ because there's an annoying bug in at least some versions: there is a hard upper limit to the timeout.

Apple's ssh has supported (and enforced) ForwardX11Timeout since at least 10.7.

https://superuser.com/questions/407218/why-does-ssh-x-forwarding-timeout-after-a-while

The default ForwardX11Timeout is 20 minutes for ssh -X, but you can set it to something large (e.g. 7d for 7 days) in .ssh/config

"Trusted" X11 forwarding via ssh -Y actually enables potentially nasty things like keystroke monitoring and screen grabs.

I'm going to try turning off the forwarding timeout and report back.