ESF Error Cheatsheet¶
Looking for help with a specific error? You can find it here! Errors are organized by ESF error code.
Property-Related Errors (ESF-1xx)¶
ESF-101 Missing Property Error¶
Explanation¶
All FindingFive objects have at least one property that must be explicitly defined. Top-level sections of the study editor may also have required properties. This error arises because the parser cannot identify the indicated required property of the indicated object or top-level study editor section.
Likely Fixes¶
Most often this is due to the omission of a required property or a typo in the definition of the property itself. Check the Study Grammar reference for the relevant object type or top-level study editor section to ensure you have all required properties included. Check for spelling or capitalization errors and for proper use of JSON formatting.
Note that property labels for FindingFive objects are subject to additional formatting conventions: they are always fully lowercase, use underscores for multi-word property labels, must be enclosed in double quotes, and must always be separated from their value by a colon (e.g., "stimulus_pattern": followed by a value).
ESF-102 Invalid Property Value Error¶
Explanation¶
Many FindingFive object properties only accept certain specific values. This error arises because the value assigned to the indicated property is not accepted by the Study Grammar.
Likely Fixes¶
Most likely you have attempted to use an invalid value for this property. In many cases, the error message will explicitly tell you which values are accepted. If not, check the Study Grammar reference for information on the accepted values for the indicated property. Check also for proper use of JSON formatting and especially for spelling or capitalization errors in the property value.
Data Validation Errors (ESF-2xx)¶
ESF-201 Missing Data Error¶
Explanation¶
Most FindingFive object properties require a value that contains some kind of data. This error arises because the indicated property value is empty or missing. For example, the value may be an empty string "", list [], or dictionary {}, but the property requires a value containing data.
Likely Fixes¶
If the value for the indicated property is indeed empty, replace it with a value containing meaningful data. Check for proper use of JSON formatting. If the value appears to contain meaningful data but this error was raised nonetheless, check for a duplicate of this property with an empty value. Check also for instances where you may have commented out lines of meaningful data.
ESF-202 Incorrect Data Type Error¶
Explanation¶
Many FindingFive object properties only accept specific data types, such as a number, string, or list. This error arises because the value for the indicated property is not one of the types accepted for that property by the Study Grammar.
Likely Fixes¶
Check the Study Grammar reference for information on accepted data types for the indicated property. If the value appears to be of an accepted type, check for proper use of JSON formatting (e.g., putting quotes around numbers or using square brackets instead of curly braces).
ESF-203 Invalid JSON Error¶
Explanation¶
Most JSON errors will be caught by the real-time JSON parser as you type and not raise an ESF error. This error arises because syntactic JSON errors were somehow not detected during real-time parsing.
Likely Fixes¶
Hopefully, the error indicates a line number and character position (char) for where the JSON parser failed. Check for proper use of JSON formatting at and around the indicated line number and character position (calculated from the start of the line). If no such information is provided, you need to narrow in on the source of the error by previewing progressively smaller chunks of your study. This will reduce the search space for finding the underlying JSON error.
ESF-204 Invalid Block Error¶
Explanation¶
All block objects must be defined in the Procedure section of the study editor, under the "blocks" property. This property takes a dictionary as its value. The individual blocks of your experiment are defined like property-value pairs in that dictionary, where the property is a user-defined block name and the value is a dictionary of property-value pairs defining that block object. This error arises when the definition (value) for the indicated block name (property) is not a dictionary of property-value pairs.
Likely Fixes¶
Check the "blocks" property of the Procedure section of the study editor and identify the block indicated by the error. Ensure that the block name is followed by a colon, and the colon is followed by a proper dictionary of property-value pairs.
Reference and Definition Errors (ESF-3xx)¶
ESF-301 Undefined Reference Error¶
Explanation¶
All user-defined FindingFive objects must have a name that can be used to reference that object elsewhere. This error arises because the indicated reference does not match any existing object names of the appropriate type (Stimulus, Response, Trial Template, or Block). This is most likely due to an error in the string representation of the reference or object name.
Likely Fixes¶
Check for spelling or capitalization errors in both the indicated reference and the target object’s name, as either could be misspelled. Remember that object names are case sensitive and even the slightest discrepancy between them will cause them not to match.
We recommend making use of the study editor’s autocompletion feature where you can, to ensure that references always point to existing objects.
ESF-302 Circular Reference Error¶
Explanation¶
Some parts of the Study Grammar allow an object property to point to another object as the source for its value. This error arises because a first object points to a second object that points back to the first object, creating an unresolvable circular reference. This error can arise in the context of any Study Grammar feature or property that uses data from one object to supply data for another object (e.g., follow-up responses).
Likely Fixes¶
Check for uses of "%s:", "%r:", or other similar cases. These are examples of special syntax used to refer to FindingFive objects in property values that do not typically expect object names. Identify the corresponding object and check for further uses of such special syntax that may be pointing back to the original object. Resolve the circular reference by removing one of the references to break the circularity. In some cases it may be necessary to create new objects to prevent circular references. If the references do not appear to be circular, double check for spelling or capitalization errors that may be inadvertently pointing to the wrong objects.
ESF-303 Duplicate Reference Error¶
Explanation¶
All FindingFive objects must have a unique name within that object’s type (Stimulus, Response, Trial Template, or Block). In addition, some object properties require unique data for their values, such as the choices of a choice response. This error arises because two or more referents of the indicated type have identical names or labels.
Likely Fixes¶
Give a unique name to all objects of a given type. Ensure all choice response choices and key mappings are distinct strings. Check for spelling or capitalization errors that may have led to accidental overlap. In some cases, objects may be redundantly defined. Remove all but one of the objects in such cases.
ESF-304 Recursive Nesting Error¶
Explanation¶
Trial nesting is currently an experimental feature that is not documented and has very limited support. The basic concept is that participants click on an interactive object within a trial that triggers a set of nested “sub-trials”, after which the participant is returned to the normal flow of the experiment. It is related to conditional branching and follow-up responses, but operates at the trial level as opposed to the block or response level. This error arises when nested trials are defined in such a way that further nesting could be triggered, which is not supported.
If this feature is interesting to you, let us know at researcher.help@findingfive.com!
Likely Fixes¶
Ensure that any nested trials that you have defined in your experiment do not themselves trigger any further trial nesting. One way to do this is to ensure that any nesting event is completely wrapped up before a subsequent nesting event can be triggered.
Content and Pattern Errors (ESF-4xx)¶
ESF-401 Stimulus Pattern Error¶
Explanation¶
The "stimulus_pattern" property of trial templates controls much of how stimuli are organized into trials. Many issues in the stimulus pattern of a trial template may be handled by other errors, but some are specific to the stimulus pattern definition. This error arises when there are issues converting the stimulus pattern into a runtime of trials for the indicated trial template.
Likely Fixes¶
Verify that your stimulus pattern definition is a properly formatted dictionary of property-value pairs that conform to the accepted properties and values specified in the Study Grammar reference for the "stimulus_pattern" property. Pay special attention to any notes or limitations on particular stimulus patterns, for example related to the number of stimuli being used that have a particular value of a custom attribute.
ESF-402 Incompatible Settings Error¶
Explanation¶
Some property values only make sense in the context of specific other property values. This error arises when the indicated properties have values that are incompatible with one another. This most often happens within a single FindingFive object, but can also occur for the settings of property-value pairs across different objects.
Likely Fixes¶
Check the Study Grammar reference for information on accepted property values and when certain values are or are not accepted (be sure to check the notes sections for each property, where applicable). Pay special attention to default values that may be causing conflicts with the property-value pairs you have explicitly defined. You may find it helpful to explicitly define all property-value pairs to avoid unintended default values.
Inheritance and Structure Errors (ESF-5xx)¶
ESF-501 Multiple Inheritance Error¶
Explanation¶
Many FindingFive objects can inherit property-value pairs from a designated parent object of the same type. Inheritance is only allowed for a single "generation", meaning no object can be both a child and a parent. This error arises when an object that inherits property-value pairs from a parent is itself used as a parent. Such multiple inheritance is not currently allowed by the Study Grammar.
Likely Fixes¶
Trace the line of inheritance for the indicated object to identify "grandparent" objects. Copy their properties into the definition of each of their child objects and remove the "parent" property. This effectively replaces inheritance with an explicit definition of all formerly inherited properties, thus removing a "generation" of inheritance. Continue this process as many times as necessary until there is at most one level of inheritance.
Branching Errors (ESF-6xx)¶
ESF-601 Duplicate Branching Outcome Error¶
Explanation¶
Conditional branching allows a procedure to be defined wherein participants are conditionally assigned to branches of your experiment based on their performance. This error arises when the same performance outcome (e.g., making a particular selection in a choice response or earning a particular accuracy score) is mapped to two different branches, which cannot be automatically resolved by the system. This can happen within the same branching block or across different branching blocks.
Likely Fixes¶
Identify all branching blocks in your experiment and ensure that they each use different triggers, and that every possible performance outcome for those triggers is directed to a unique branch. Check also for redundant branching blocks, for example resulting from a copy-paste error.
Block-Level Errors (ESF-7xx)¶
ESF-701 Unequal Trial Template Length Error¶
Explanation¶
The "pattern" property of a block controls how the trials generated by that block’s trial templates are organized. It is defined as a dictionary that contains an "order" property and a "repeat" property. If the "order" property has a value of "alternate", "alternate_random", or "pseudorandomized_template_traversal", then every trial template defined under the "trial_templates" property of that block must contain the same number of trials. This is because these block ordering patterns involve sampling trials from one template at a time with the constraint that consecutive trials can not be sampled from the same template. This error arises when one of these orders is used with trial templates of unequal lengths.
Likely Fixes¶
Check the object definitions of each trial template named in the "trial_templates" property for the indicated block. Verify that each template generates the same number of trials, and make any changes necessary to ensure that they do. In some cases, sampling may be used to limit the total number of trials that the template will generate. If it is not possible to force all templates to the same length, you may need to rethink the block ordering pattern you are attempting to use.
ESF-702 Exceeding Max Trials Error¶
Explanation¶
To promote an optimal participant experience, FindingFive puts a limit on the number of trials that can be generated in a given block. By default, this maximum is 250 trials. This error arises when the combined total number of trials to be generated by the "trial_templates", "cover_trials", and "end_trials" properties of the indicated block exceeds this maximum.
Likely Fixes¶
If your experiment design allows, break the indicated block up into multiple separate blocks. If you do not think your block should be generating so many trials, ensure you are not inadvertently generating more trials than intended (check the "pattern" property of the indicated block and the "stimulus_pattern" property of each trial template used in that block). If absolutely necessary, you can override the maximum with a higher value, but we recommend avoiding this option if possible.