Troubleshooting

Collection of known potential problems and their solutions

This page is dedicated for Troubleshooting. Known errors and problems will be listed here with a possible solution for solving this issue. If you solved a problem that might be relevant for others as well, feel free to contact Maximilian (,Adam or Natalia) so that it can be added to this page as well.

1 General

If you encounter an error

• Check the error message, maybe copy/paste it to Google/an AI to get a first idea of what is wrong
• Check if all necessary ressources are sourced (e.g. did you include ml freesurfer before opening a volume to check for noise scans)
• Check if your working directory is set correctly, if not, correct that with cd /desired/path/ (e.g. when you try to remove the noise scans)
• Check if the paths in your command are correct. In some scripts you define you path in a variable, like $SUBJECTS_DIR or $niidir. If you want to only run a specific line of code separately, you might have to write out the complete path

2 fMRIprep

2.1 I ran fMRIprep but no distortion correction happened

2.1.1 Detection of this Problem

2.1.1.1 Error Message

This problem might occur with a corresponding error message (and the fMRIprep command stopping)

2.1.1.2 Silent error

It can be hard to realize this issue as the output might not be visible anymore, or the problem “occurs silently” (no error message are shown at all).

If the distortion correction was successful, the subject’s .html should include a section \(B_0\) field mapping. As you can see in the image below, this would be shown at the top of the file where the different sections are listed as well:

If the distortion correction failed silently (thus, without an explicit error that is printed somewhere), the section is missing as whole and is not shown at the top of the .html file:

2.1.2 Solution

• you might be using a wrong BIDS specification in the fmap’s json file. See Information about BIDS uri, or the corresponding wiki entry.

• If the content of the fmap’s .json file uses a different naming convention than necessary for your version of fMRIprep, no distortion correction is applie

\(\to\) Follow this wiki entry to check and update the entries of the fmap’s .json file

2.2 ValueError: Reference passed is not aligned with spline grids

This error sometimes occurs by chance, but should not appear regularly. It is caused by the coregistration algorithm of fmriprep itself. There are two options you can try:

1. Try a different version of fMRIprep

2. Transform your T1w scan

2.2.1 Transform your T1w scan

Transforming your T1w scan to avoid this error is not the ideal solution, but it is a good workaround for this complex problem.

To transform your T1w scan:

1. Load your structural scan in freeview (identical process as described here for a functional scan)

2. In the menu-bar in freeview (top-left), select Tools > Transform Volume...

3. In the resulting window, select Transform in the top menu and change the value in the second “line” (= Y (P-A)) to -2.5 (with the slider or enter the number directly). This will shift the T1w scan 2.5mm in the posterior direction. Subsequently, select Save Volume As

4. You can simply overwrite the existing T1w file which should already be selected (you could always reverse this step with the described method). Make sure to select the option Do not resample voxel data when saving (only update header)!

\(\to\) when you run freesurfer with this transformed T1w scan, the “Spline Grid Error” should not occur anymore.

2.3 If using already run FreeSurfer recon-all output and have specified an expert-opts file then fMRIprep shows multiple errors

\(\to\) In the directory that has the prerun recon-all there is a folder scripts that saves the expert-opts file. Removing this file allows fMRIprep to run

2.4 I ran fMRIprep and the distortion correction of the data is too extreme

An example of poor distortion correction

This is an issue with certain issues of fMRIprep. Using fMRIprep version 20.2.7 may be needed to avoid the extreme distortion correction (newer versions of fMRIprep haven’t been tested)

2.5 fMRIprep fails silently (i.e. gives no error) on coregistering the functional to the structural scan

\(\to\) the solution is (if your structural and functional scans are from the same session) to add the following flag:

`--bold2t1w-init header`