Scanpy troubleshooting

Most Scanpy failures on the platform trace to one of four causes — an input the pipeline can't read, QC thresholds that filter out every cell, a missing parameter for an extension workflow, or a dataset that's too large for the GPU. This page maps each symptom to its fix. Check the job logs for the exact error string first — the pipeline reports specific messages for these cases.

Input rejected

The Scanpy job accepts only an AnnData .h5ad file referenced by an S3 URI or HTTPS URL ending in .h5ad. It validates both, so:

• A CSV, MTX, or 10X directory is rejected — convert it to .h5ad first.
• A URL that doesn't end in .h5ad, or isn't s3:///https://, fails validation before the run starts.
• If the file loads but has no gene symbols in var, marker-gene steps can't annotate — confirm gene names are present.

No cells left after filtering

If QC removes every cell, the run stops with a "no cells remain" error. This usually means the thresholds are too strict for your data:

• Relax max_mito_percent — the platform defaults to 5%, which is aggressive. Raise it toward 10–20% for datasets with higher mitochondrial content.
• Lower min_genes — the 200-gene floor can be too high for shallow-depth protocols.

Batch-correction workflow errors

The harmony_integrate, scanorama_integrate, and combat_correct workflows require a batch_key naming the obs column that holds sample/batch labels. If it's missing or names a column that doesn't exist, the run fails — set batch_key to a real obs column.

Empty or too-few clusters

• Raise resolution for more, smaller clusters (default 1.0; try 1.2–1.5).
• If clustering yields a single cluster, filtering may have removed too much signal — loosen QC.
• Confirm the full or clustering workflow ran (the qc and de workflows don't produce a fresh clustering on their own).

Memory or timeout issues

The GPU pipeline runs on a T4 (16 GB VRAM) with a 10-minute timeout, which handles up to roughly a million cells:

• Filter more aggressively to shrink the working set before dimensionality reduction.
• Lower n_top_genes so PCA operates on fewer features.
• Reduce n_pcs (50 is usually plenty).
• For very large atlases, subsample before the full run, then apply the clustering to the whole set once parameters are settled.

Read next