QSIRecon: 'No atlas images found' ValueError in collect_atlases with a custom BIDS atlas dataset

QSIRecon: 'No atlas images found' ValueError in collect_atlases with a custom BIDS atlas dataset

TL;DR

The error means the BIDS layout QSIRecon built from your atlas dataset returned zero files for its template + dseg query, even though a dseg file looks present on disk. In almost every case the cause is on the indexing side, not the tractography side: the path passed to --datasets is not the atlas dataset root, the label string in --atlases does not exactly match the atlas-[label] folder, or the dseg filename does not parse into the entities the query asks for. Verify those three things, reproduce the query standalone with PyBIDS, fix the naming or layout, and rerun one subject before scaling up.

Verbatim error

Errors found in atlas collection:
No atlas images found for CND0012001muse with query {'template': 'MNI152NLin2009cAsym', 'suffix': 'dseg', 'extension': ['.nii.gz', '.nii']}
ValueError, raised from qsirecon/utils/atlases.py in collect_atlases (QSIRecon 26.0.1)

Steps

1. Print the exact expanded arguments before rerunning. Echo the shell variables so you see the final strings QSIRecon receives for --datasets [label]=[path] and --atlases [label]. Success check: the label in both flags is character-for-character identical to the suffix of the atlas-[label] folder on disk. A variable that expands differently in the two flags (for example an extra subject prefix) is the single most common cause.
2. Confirm the --datasets path is the atlas dataset root. The root must contain datasetdescription.json (with DatasetType set to atlas) and the atlas-[label] folder inside it. Passing the atlas-[label] folder itself, or the parent of the root, makes the layout index the wrong tree and the query finds nothing. Success check: listing the path you passed shows datasetdescription.json and the atlas folder side by side.
3. Check the dseg filename entities. The image inside atlas-[label] should be named atlas-[label]space-MNI152NLin2009cAsymdseg.nii.gz, with the matching [label]dseg.tsv (columns index, name, roiresolution) beside it. The space value must match the template name in the error query exactly. Success check: the filename has no extra entities, typos, or double extensions between the space entity and the dseg suffix.
4. Reproduce the indexing standalone. Build a PyBIDS BIDSLayout on the atlas dataset root and run the same query (template MNI152NLin2009cAsym, suffix dseg) and print the results. Success check: the query returns your dseg file. If it returns empty outside QSIRecon, the problem is filename parsing, a .bidsignore entry, or a JSON sidecar whose SpatialReference disagrees with the filename, not QSIRecon logic.
5. If step 4 is still empty, temporarily move the non-space native-space dseg file out of the atlas folder and rerun the query. A second dseg for the same label can confuse collection and mask the spaced file. Success check: the query now returns the MNI-space file.
6. Fix whichever check failed, then rerun the single-subject test recon with the same flags. Success check: collect_atlases logs the atlas as found and the run proceeds past atlas collection to connectivity matrix generation.

When this applies

• QSIRecon 26.x with a custom atlas supplied via --datasets and --atlases
• Failure occurs inside collect_atlases before any tractography or matrix step runs
• The atlas dataset follows the BIDS atlas layout (dataset_description.json plus an atlas-[label] folder)

When this does not apply

• Errors that name a built-in QSIRecon atlas rather than a custom one
• Runs that get past atlas collection and fail during tractography or matrix writing
• QSIPrep (not QSIRecon) preprocessing failures

Variant phrasings

Errors found in atlas collection in QSIRecon 26.0.1

Same failure; the wrapper message appears first in the log and the 'No atlas images found' line underneath it is the actionable part.

Custom atlas query returns empty in PyBIDS

If the standalone layout query in step 4 returns nothing, treat the skill as a filename/layout parsing problem and work steps 2, 3, and 5 in order.

Why it happens

collect_atlases trusts the PyBIDS index completely. It never scans the folder with its own eyes, so a file that looks right in a directory listing can still parse into entities the query does not ask for, sit one directory level away from where the layout was rooted, or be shadowed by a sibling file. The ValueError is the query result (zero files) surfacing, not a corrupted atlas.

Edge cases

• Per-subject atlases generated in a loop: build the label string once and reuse it for the folder name, the --datasets label, and the --atlases value so the three can never drift apart.
• Atlas datasets assembled on Windows or copied between filesystems: check for hidden characters or a trailing space in the folder name.
• If the standalone PyBIDS query works but QSIRecon still fails, compare the QSIRecon version's bundled layout config against your PyBIDS version; entity naming (template vs space) changed across releases.

Provenance

Resolved from the public thread: https://neurostars.org/t/qsirecon-construct-connectivity-matrices-based-on-a-custom-atlas-for-each-individual/36448

In the Neurostars thread 'QSIRecon: construct connectivity matrices based on a custom atlas for each individual' (opened Oct 9, 2026; OP follow-up Oct 14 still unanswered): a 1,262-scan DTI dataset run through QSIPrep + QSIRecon with a per-subject MUSE atlas dataset on QSIRecon 26.0.1 fails in qsirecon/utils/atlases.py collect_atlases with 'No atlas images found for CND0012001muse' for the MNI152NLin2009cAsym dseg query, despite an MNI-space dseg file being present in the atlas folder. Source: https://neurostars.org/t/qsirecon-construct-connectivity-matrices-based-on-a-custom-atlas-for-each-individual/36448