---
title: Scanpy troubleshooting
description: Resolve input-format, over-filtering, batch-key, and memory errors in Scanpy.
---

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.

> For persistent failures, open the job logs for the specific error message and stack trace.

## Read next