PsychoPy error messages

Find and make sense of error messages in PsychoPy


This post describes where to find error messages in PsychoPy and to how understand and fix some of the most common error messages.


Jan Derrfuss


June 6, 2022


Given that our research focuses on errors, I thought it would be fitting to dedicate our first blog post to error messages in PsychoPy. In my experience, PsychoPy learners often struggle with error messages generated by PsychoPy. Firstly, they find it difficult to actually locate them. Secondly, they have difficulties to understand what they mean and how to fix them.

Errors vs alerts and warnings

Before we have a closer look at some error messages, it is important to understand that errors will stop an experiment from running, whereas this is not necessarily the case for an alert or a warning. Alerts and warnings notify you of potential issues that PsychoPy has identified. For example you might get an alert that your experiment was built in a previous version of PsychoPy:

Alert 4052:Experiment was built in a past version of PsychoPy (2020.2.8), saving it in this version may add parameters which cannot be parsed.
    For further info see

Or a warning that the actual screen resolution doesn’t match the requested one:

WARNING     User requested fullscreen with size [1920 1080], but screen is actually [1680, 1050]. Using actual size

The PsychoPy documentation has a page with an overview of possible alerts. As noted on this page, you will need to check whether or not they are an issue for your experiment. However, note that an alert or warning that is not accompanied by an error message will not stop your experiment from running.

Error messages appear in the Runner

The Runner window is where PsychoPy error messages are displayed. Admittedly, the section where error messages appear is a bit inconspicuous: It is called Stdout:

The PsychoPy Runner window with an arrow pointing at the Stdout section.

Stdout stands for standard output.1


PsychoPy error messages appear in the Stdout section of the Runner window.

Common PsychoPy error messages

Below I will describe some common error messages. I will also describe possible underlying problems and how these can be fixed. Angle brackets (<>) in the examples below are place-holders for variable or file names. Note that there might be other underlying issues apart from the ones mentioned below, but hopefully the ones listed below will give you some idea of what the problem could be.

Note that it might be necessary to scroll up in the Stdout section to find the error message.2 Another option is to copy and paste the contents of Stdout to a text editor (via the usual Cmd+A → Cmd+C → Cmd+V, if you’re running macOS) and to search for “Error” in the text editor.

NameError: name ‘<variable_name>’ is not defined

Underlying issue—option 1: The variable name used in a component does not match the variable name used in the conditions file. For example, the file name field in an Image component might refer to $Img:

File name field of an Image component.

On the other hand, the conditions file might have a column with the header img:

Screenshot of a conditions file.

Solution: Make sure variable names in PsychoPy components and the conditions file match exactly. Capitalisation is relevant. So, in this example, all you would need to do is change your file name field in the Image component to this:

File name field of an Image component.

Underlying issue—option 2: The variable name in a code component does not match the name of the component to which it refers. For example, a code component that is meant to check whether or not a response was correct might use resp.corr,

if resp.corr == 1:
    fbMsg = "Correct"
    fbMsg = "Wrong!"

However, the Keyboard component might actually be called key_resp:

Name field of a Keyboard component.

Solution: Make sure the variable names in code components match those of the other code components. In the example, the code component should use key_resp.corr:

if key_resp.corr == 1:
    fbMsg = "Correct"
    fbMsg = "Wrong!"

Underlying issue—option 3: A parameter of a component that is meant to be updated from trial to trial is set to constant. For example, the text field of a Text component might use $stim to indicate that the stimulus will be changing from trial to trial, but it is nevertheless set to constant:

The text field of a Text component.

Solution: Choose set every repeat for parameters that should be updated from trial to trial. In the example:

The text field of a Text component.

KeyError: ‘participant’

Underlying issue: The Experiment Settings are missing the field participant (e.g., this field might have been renamed to Participant).

Per default, PsychoPy insists on the field participant (not capitalised!) in the Experiment Settings. It uses the value assigned to this variable in the output data filename. You can see this by going to Experiment SettingsDataData filename. By default, this is:

u'data/%s_%s_%s' % (expInfo['participant'], expName, expInfo['date'])

Solution: Either use the field participant in the Experiment info or change the Data filename. For example, if for whatever reason you would like to use Participant, change Data filename to this:

u'data/%s_%s_%s' % (expInfo['Participant'], expName, expInfo['date'])


The full error message will be something along these lines:

psychopy.exceptions.ConditionsImportError: Conditions file <file_name>: Parameters (column headers) cannot contain punctuation or spaces
"<variable_name_in_header> "

For example, the error message might say:

psychopy.exceptions.ConditionsImportError: Conditions file conditions.xlsx: Parameters (column headers) cannot contain punctuation or spaces
"image "

Underlying issue: There is a space after one of the column headers in the conditions file. This is one of the cases where the error message pretty much tells you what exactly the problem is. Yet, I’ve repeatedly come across students staring at this message for a couple of minutes not realising that it indicates that there is a space after one of the column headers. Just in case you missed it: Note that the error message says "image[space]".

Solution: Remove the space after the column header.

OSError: Couldn’t find image <file_name>; check path?

Underlying issue: It’s pretty much what it says on the tin. PsychoPy can’t find an image. There are a number of reasons as to why this might happen:

  • The path to the image provided in the component could be wrong. E.g., you might have asked PsychoPy to look in the folder images, but might have forgotten to move your images to this folder.
  • The file name of the image file does not match the file name PsychoPy is looking for. Imagine PsychoPy is looking for an image called myStim.jpg. If the image file has any of these names, the above error will be raised:
    • mystim.jpg
    • myStim.JPG
    • myStim.jpeg
    • myStim.png (obvious, but easily forgotten if there is a large number of images in the experiment, a few of which might be in a different format)

Solution: Make sure the file names PsychoPy is looking for and the actual file names match exactly. Capitalisation is relevant. Make also sure the paths match.

SyntaxError: invalid syntax

Underlying issue: There is probably an issue with a Code component. Check the error message for additional details. For example, look for information on the tab and line number:

  • Python Syntax Error in 'Begin Routine' tab.
  • on line number <x>

Solution: Fix your code. That is of course easier said than done if you have little experience with coding in Python. Keep in mind that there is a friendly community of PsychoPy users out there. If you ask a code-related question on PsychoPy Discourse, please keep in mind to add your code and the error message in full to your post. Please make sure to surround your code with three back quotes at the beginning and the end, so it is displayed correctly on Discourse:

if key_resp.corr = 1: # note the missing equals sign
    fbMsg = "Correct"
    fbMsg = "Wrong!"

Note that if you click on the preformatted text icon (i.e., </>), Discourse will add these back quotes for you.

Dealing with other error messages

As so often in life, asking your internet search engine of choice is a promising strategy. If you go for this approach, make sure to remove information that is specific to your experiment. For example, if you like to use quotes to search for phrases, this will not be successful:

psychopy "NameError: name myUnusualVariableName is not defined"

Instead, search for this:

psychopy "NameError: name" "is not defined"

Of course, you can also search directly on PsychoPy Discourse. Note that Discourse has a number of advanced filters for searching that might come in handy. For example, you can search for posts from a specific person or topics that have been marked as solved.


  1. This is a very old page, but at least on the first two pages of Google hits, in my view it is the most beginner-friendly explanation of the concept “standard output”.↩︎

  2. In fact, once I’ve had a look at the alerts, I tend to hide the alerts section by clicking on the word “Alerts” to have more space for Stdout (you might need to click twice on “Alerts” for this to work).↩︎