Every entry below is sourced from a real, public GitHub issue — linked so you can verify and read the full thread yourself. No invented scenarios.
Why this post exists
If you're searching "squidpy error" or "Load10X_Spatial error" at 11pm trying to get your analysis to run, you don't need another tutorial — you need to know if someone else hit your exact wall and how they got past it. So instead of writing a generic troubleshooting guide, this rounds up real, documented issues from the Squidpy and Seurat GitHub repos.
Quick decision guide based on the patterns in this post — start here, then check the specific issue thread for your case.
1. Squidpy: cannot import name '_set_default_colors_for_categorical_obs'
The error, reported in squidpy#1107:
ImportError: cannot import name '_set_default_colors_for_categorical_obs' from 'scanpy.plotting._utils'
Root cause: This is a version compatibility break, not a bug in your code. Scanpy 1.12 renamed an internal function (dropped the leading underscore), and the squidpy version the user had installed was still trying to import the old private name.
The fix: Upgrade squidpy to a version released after this was patched, or pin a compatible scanpy version. This is a good reminder that with fast-moving scverse-ecosystem packages, import errors right after pip install are very often a version mismatch between squidpy and scanpy, not something wrong with your setup.
pip install --upgrade squidpy scanpy
2. Squidpy: cannot import name 'SparseCSCView'
A related but distinct import failure, squidpy#928. Same category of problem: an internal class/function squidpy depends on moved or was renamed upstream in anndata or scanpy. If you hit any "cannot import name X from Y" error on import squidpy, the first thing to check isn't your code — it's whether your squidpy, scanpy, and anndata versions were released around the same time. Mixing a brand-new squidpy with an old anndata (or vice versa) is the most common cause of this entire category of errors.
3. Seurat: Load10X_Spatial JSON / file structure errors
This one shows up repeatedly across multiple issues — #9628 ("lexical error: invalid char in json text"), #10091, #10108, #9536, and #7677. If you're getting any kind of file-not-found or JSON-parsing error from Load10X_Spatial(), you're in very good company — this is the single most reported spatial-loading pain point in the Seurat repo.
What's known: the function expects an exact SpaceRanger output folder structure (filtered_feature_bc_matrix.h5, scalefactors_json.json, and a spatial/ subfolder with specific image filenames). In at least one case (#9628), a user confirmed they had this exact structure and the error still occurred — meaning the fix isn't always as simple as "check your folder structure."
Honest caveat: We don't have a single universal fix to report here — the public threads don't converge on one root cause across all reports (some are SpaceRanger version mismatches, some are bin-size related in newer Visium HD data). If you hit this, the most useful first step is comparing your SpaceRanger output version against what Seurat's current release expects, and checking the specific issue thread closest to your Seurat version for the latest comment.
4. Squidpy: confusion about what co_occurrence actually normalizes by
Covered in our post "Squidpy vs Seurat for Spatial Transcriptomics: Which Tool Should You Use in 2026?" — worth repeating here because it's a real source of misinterpreted results, not just an error message. In squidpy#1205, a user pointed out that sq.gr.co_occurrence normalizes by the neighbor cell type's total frequency, not the center cell type's frequency — which is counterintuitive if you're expecting it to directly estimate P(neighbor=i | center=c).
Why this matters: if you're reporting co-occurrence z-scores in a paper, make sure you understand and state the direction of the conditional probability correctly — getting this backwards changes how the enrichment should be interpreted.
5. Squidpy: calculate_image_features() error with tutorial data (currently open)
Flagging this one as unresolved as of writing (squidpy#826) — even using squidpy's own official tutorial data, users have reported this function throwing an error. If you're hitting this, it's not just you; check the issue thread for the latest status before assuming you've misconfigured something.
Takeaway
A surprising number of "errors" in this ecosystem aren't really about your data or your code — they're version-compatibility breaks between scanpy/anndata/squidpy, or SpaceRanger-output-format mismatches that even Seurat's own example data can trip on. Before spending hours debugging your own pipeline, it's worth a quick search of the relevant GitHub issues — there's a good chance someone already filed it.
This post will be updated as these issues get resolved or new common ones emerge.
Get the complete pack
Squidpy Complete Analysis Pack — 10 Notebooks
All 10 notebooks from this series in one download — SVGs, neighborhood enrichment, co-occurrence, ligand-receptor, and the complete pipeline. Verified and ready to run on your own data.
Get it for $19 →
No comments:
Post a Comment