Trouble shooting

Table of Contents

• General
• Pickle protocol 5
• MacOS: Framework build
• Quitting iPython
• MNE GUI problems
  • MRI model is missing from 3d view
  • PyFace error
  • Function involving brain plots freezes/PyThreadState_Get error
  • VTK missing
  • Black image
• Notebooks
  • Brain plots broken

General

• For most errors, Python prints an error message (a traceback) that should hint at what is wrong. If you can’t figure out what it is, feel free to email me.

• Sometimes these are not outright errors but just warnings: see Warnings.

• For problems that are not associated with an explicit error message, have a look at Problems-without-traceback.

Pickle protocol 5

ValueError: unsupported pickle protocol: 5

Pickle protocol 5 was introduced in Python 3.8, and older versions of Python cannot read files saved with this protocol. The solution is usually to either switch to Python ≥ 3.8, or to open the files in Python ≥ 3.8 and resave them with protocol 4.

MacOS: Framework build

On macOS, the GUI tool Eelbrain uses requires a special build of Python called a "Framework build". You might see this error when trying to create a plot:

SystemExit: This program needs access to the screen.
Please run with a Framework build of python, and only when you are
logged in on the main display of your Mac.

In order to avoid this, Eelbrain installs a shortcut to start IPython with a Framework build:

$ eelbrain

This automatically launches IPython with the "eelbrain" profile. A default startup script that executes from eelbrain import * is created, and can be changed in the corresponding IPython profile.

Quitting iPython

Sometimes after using GUIs iPython seems to get stuck during quitting after this line:

Do you really want to exit ([y]/n)? y

In those instances, pressing ctrl-c usually terminates iPython immediately.

MNE GUI problems

The MNE GUIs (mne coreg and mne kit2fiff) are particularly vulnerable to dependency conflicts. This section describes some common errors when trying to open MNE-Python GUIs.

MRI model is missing from 3d view

In recent versions sometimes the 3d view shows fiducial points but does not show the MRI head model, even after changing the MRI directory and MRI subject. This can be fixed by specifying the subjects-directory before starting the GUI, with a command-line argument:

$ mne coreg -d path/to/mri_subjects_directory

Alternatively, the subjects-diretory can also be specified through the SUBJECTS_DIR environment variable.

PyFace error

RuntimeError: No pyface.toolkits plugin could be loaded for qt4

MacOS:

• Install pyqt5 with pip: $ pip install pyqt5 vtk mayavi

• Then tell the GUIs to use it: $ export QT_API=pyqt5

• The latter line has to be re-run whenever a new terminal is opened. It might be useful to add it to the bash_profile.

Function involving brain plots freezes/PyThreadState_Get error

If a function involving mayavi brain plots freezes or crashes with the following error:

Fatal Python error: PyThreadState_Get: no current thread

Try reinstalling VTK with $ pip install vtk.

VTK missing

DistributionNotFound: The 'vtk' distribution was not found and is required by the application

This might be because of a bug leading to an incorrect version of VTK being installed. Check $ conda list vtk. If the installed version is not 8.1.1, run the following command:

$ conda install -c conda-forge vtk=8.1.1

If VTK 8.1.1 is installed and the error persists, VTK has to be installed from a different source. Install it from pip with:

$ pip install vtk

If there are still problems, also re-install QT and Mayavi:

$ pip install pyqt5 mayavi

Black image

When the PyQT5 backend can’t be initialized, the rendered image in the middle of the GUI stays black. This can probably be solved by installing pyqt5 with pip:

$ pip install pyqt5 mayavi

Notebooks

Brain plots broken

When brain plots look like static, this can sometimes be solved by installing pyqt5 with pip:

$ pip install pyqt5