fMRIPrep: FreeSurfer license not found

Software Support
,
1

Summary of what happened:

Hello,

I am trying to preprocess data using fMRIPrep, but have been getting an error indicating that a valid Freesurfer license is required, despite the fact that I have a Freesurfer license.

Any idea how I might go about resolving this issue? Any suggestions or help would be greatly appreciated. And please let me know if you need additional information.

I have tried multiple steps including:

export FS_LICENSE=/path/to/freesurfer/7.3.2/.license

And including the –fs-license-file flag in the pipeline with the path to the license.

I have also tried multiple different versions of FreeSurfer (7.4.1 and 7.3.2) and in all the cases I have tried I still end up with the same error.

I even tested a FreeSurfer command (mri_convert) and it ran without any issue, which to me indicates this FreeSurfer license should be working.

Thank you!

Brandon

Command used (and if a helper script was used, a link to the helper script or the command generated):

fmriprep  $bids_dir $out_dir ‘participant’ --skip_bids_validation --participant-label $subj

Version:

25.2.5

Environment (Docker, Singularity / Apptainer, custom installation):

Linux HPC (moderator note - but how? sinuglarity, docker, etc?)

Data formatted according to a validatable standard? Please provide the output of the validator:

PASTE VALIDATOR OUTPUT HERE

Relevant log outputs (up to 20 lines):

ERROR: a valid license file is required for FreeSurfer to run. fMRIPrep looked for an existing license file at several paths, in this order: 1) command line argument ``–fs-license-file``; 2) ``$FS_LICENSE`` environment variable; and 3) the ``$FREESURFER_HOME/license.txt`` path. Get it (for free) by registering at

Screenshots / relevant information:

2

Hi @btaraku and welcome to neurostars!

In the future please use the prepopulated Software Support post template for these questions, which prompts you to give us important information to help us debug. I have done my best to reorganize your post accordingly but didn’t have enough information for everything.

It is not clear what fMRIPrep version you are using or how you are running it (e.g. Singularity vs. Docker vs. bare-metal Python). Knowing this will help us debug. We recommend using containers. If using a container, please provide the full command, including the singularity run / docker run preamble.

Best,

Steven

3

Hi Steven,

Thank you for the response and reorganizing my post. Apologies for not using the pre-populated posts, I will keep that in mind for next time.

I am using fMRIPrep version 25.2.5, and running it as bare-metal python, and load other dependencies via the module load command on our server.

Thank you,

Brandon

4

Hi @btaraku,

Can you try using a container? Without knowing more about the installation and module infrastructure, it is hard to precisely debug.

Best,
Steven

5

Hi Steven,

Thanks for the suggestion, I will follow up with our IT admin about setting up fMRIPrep using a container.

6

Hi Steven,

I am now running the fMRIPrep pipeline as a container, and it is still giving the same license error as before. Here is the command I am running:

fmriprep_app=/path/to/software/fmriprep/containers/25.2.5/fmriprep-25.2.5.sif
$fmriprep_app $bids_dir $out_dir 'participant' --skip_bids_validation --participant-label $subj

And the error occurring is the same as before:

ERROR: a valid license file is required for FreeSurfer to run. fMRIPrep looked for an existing license file at several paths, in this order: 1) command line argument \`\`–fs-license-file\`\`; 2) \`\`$FS_LICENSE\`\` environment variable; and 3) the \`\`$FREESURFER_HOME/license.txt\`\` path. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

I tried to export the license as:

export FS_LICENSE=/path/to/software/fmriprep/containers/25.2.5/FS_LICENSE/license.txt

And using the --fs-license-file, and neither of these worked.

Do you have any other suggestions on how to resolve this so the pipeline can find the license?

Thank you,

Brandon

7

Hi @btaraku,

In the future please format your code with tickmarks / the </> button for readability. You can see I edited your above post for you this time.

I recommend using singularity run / apptainer run syntax. Also you should use a working directory that is outside bids_dir. It’s likely that your syntax did not bind any important files like the license to the container so it couldn’t find it.

Try

apptainer run \
  --contain-all \
  -B /path/to/your/license:/license.txt:ro \
  -B ${bids_dir}:/bids \
  -B ${out_dir}:/out \
  -B ${work_dir}:/work \
  ${fmriprep_app} \
  /bids /out participant \
  -w /work \
  --participant-label $subj \
  --fs-license-file /license.txt \

Best,
Steven

8

Hi Steven,

It was just suggested that I try copying the Freesurfer license to my $HOME directory, export that, and then try running, and surprisingly that seemed to work.

It looks like the pipeline is running past the previous point where it was crashing and I don’t see any license errors, so it seems that this specific issue is resolved.

Thank you for the container suggestion and providing feedback!

-Brandon

9

Hi @btaraku,

Yes, containers bind home directory by default, unless you include --contain-all. I generally recommend including --contain-all and not mounting home directory, because you could unknowingly introduce software conflicts with anything you have installed in home directory. It is also in general less portable/sustainable if you rely on user specific home directories.

Best,
Steven