Troubleshooting¶

A symptom → cause → fix table for the errors STELLAR users hit most often. Each entry shows the error line you'll actually see, what's causing it, and the exact command or config snippet that resolves it.

If your problem isn't here, run stellar doctor first — it catches the majority of misconfigurations before they reach uvicorn.

Input / config errors¶

`FileNotFoundError: Seurat .rds not found` or `h5ad not found`¶

Symptom

stellar ingest: ...
FileNotFoundError: Seurat .rds not found: /abs/path/data/raw/my.rds

or

[Errno 2] No such file or directory: 'data/raw/pbmc_3k.h5ad'

Cause — input.matrices[*].path in stellar.yaml points at a file that doesn't exist relative to the project root (the directory containing stellar.yaml).

Fix — check the path and run stellar doctor:

stellar doctor --config stellar.yaml
# ✗ [input.matrices.primary] input matrix not found: /abs/path/data/raw/my.h5ad

Either move the file into place or update the config:

input:
  matrices:
    - name: primary
      path: data/raw/correct_name.h5ad   # relative to stellar.yaml
      role: primary

`cohort.cell_type_column='cell_type' not in obs`¶

Symptom

✗ [input.matrices.primary] cohort.cell_type_column='cell_type' not in obs;
  available cols: ['CellType', 'donor', 'condition_raw', ...]…

Cause — your h5ad's obs has the column under a different name than stellar.yaml declares.

Fix — point stellar.yaml at the actual column. No need to rename columns in the h5ad:

cohort:
  cell_type_column: CellType      # match what's in obs
  condition_column: condition_raw
  donor_column:     donor

Re-run stellar doctor; once it's clean, run stellar ingest.

`Rscript is not on PATH`¶

Symptom

stellar.core.io.seurat.SeuratConversionError: `Rscript` not on PATH.
Install R 4.x to enable Seurat inputs. See docs/recipes/from_seurat.md.

Cause — your input.matrices[*].path ends in .rds, but the machine running stellar ingest doesn't have R installed.

Fix — install R and either SeuratDisk or sceasy:

# Debian / Ubuntu
sudo apt install r-base

# Inside R
install.packages("remotes")
remotes::install_github("mojaveazure/seurat-disk")
# OR
remotes::install_github("cellgeni/sceasy")

Verify:

Rscript -e 'library(SeuratDisk); cat("ok\n")'
# → ok

The full Seurat-input recipe lives at recipes/from_seurat.md.

`Need either SeuratDisk or sceasy installed in R`¶

Symptom

SeuratConversionError: Rscript exited 1 ...
--- stderr ---
Error: Need either SeuratDisk or sceasy installed in R.

Cause — R is on PATH but neither converter package is installed.

Fix — inside R, install one:

install.packages("remotes")
remotes::install_github("mojaveazure/seurat-disk")

If both are installed, SeuratDisk wins automatically (it's the lossless path).

`readRDS produced a SingleCellExperiment object — expected Seurat`¶

Cause — your .rds is a SingleCellExperiment, not a Seurat object.

Fix — convert on the R side first:

sce <- readRDS("my.rds")
seurat_obj <- Seurat::as.Seurat(sce, counts = "counts", data = "logcounts")
saveRDS(seurat_obj, "my_as_seurat.rds")

…then point stellar.yaml at my_as_seurat.rds.

Build / runtime errors¶

`no built atlas yet — run stellar ingest`¶

Symptom

stellar doctor:
  ⚠ [artifacts] no built atlas yet — run `stellar ingest` to create
    /abs/path/data/atlas.duckdb

…or, at serve time:

duckdb.IOException: IO Error: ... atlas.duckdb does not exist

Cause — stellar serve was called before stellar ingest.

Fix

stellar ingest --config stellar.yaml
stellar serve --config stellar.yaml

`<name>.h5ad is newer than the built DuckDB`¶

Symptom — stellar doctor warns:

⚠ [artifacts] my.h5ad is newer than the built DuckDB — re-run
  `stellar ingest` to pick up changes

Cause — you edited the h5ad (or its .rds source) after the last ingest; the on-disk DuckDB + Lance stores are stale.

Fix

stellar ingest --config stellar.yaml

The build is idempotent — it drops and recreates the stores.

`ImportError: cannot import name 'lance'` / `Lance ImportError`¶

Symptom

ImportError: cannot import name 'lance' from partially initialised module

or

ModuleNotFoundError: No module named 'lance'

Cause — you installed the wrong package on PyPI: there's both a lance (unrelated) and a pylance (the real LanceDB storage layer that imports as lance). STELLAR's pyproject.toml pins pylance>=0.21 — if you've installed lance directly it will shadow pylance.

Fix

pip uninstall lance
pip install --upgrade pylance lancedb

`lance.list_tables() error` / opening Lance table fails¶

Symptom

lance.LanceError: ...
ValueError: table 'primary' does not exist in ...

Cause — the Lance directory under data/lance/ is missing or corrupt — usually because the last stellar ingest was interrupted before completing.

Fix — re-run ingest. It overwrites in place:

rm -rf data/lance/        # safe — ingest rebuilds it
stellar ingest --config stellar.yaml

LanceDB / DuckDB version mismatch on import¶

Symptom

lancedb.exceptions.LanceDBException: file written with newer version of Lance

or

duckdb.IOException: Trying to read a database file with version number 67,
but we can only read version 64.

Cause — you upgraded lancedb / duckdb after building the stores, and the on-disk format moved forward (or vice-versa: you downgraded).

Fix — rebuild the stores against the installed library versions:

rm -rf data/lance/ data/atlas.duckdb data/parquet/
stellar ingest --config stellar.yaml

Copilot module errors¶

`ANTHROPIC_API_KEY not configured`¶

Symptom — POST /api/copilot/ask returns HTTP 503:

{"detail": "ANTHROPIC_API_KEY not configured (set env var or write <project_root>/.env)"}

Cause — the copilot module is enabled but the Anthropic key is neither in the environment nor in <project_root>/.env.

Fix — either set the env var:

export ANTHROPIC_API_KEY=sk-ant-...
stellar serve --config stellar.yaml

…or drop it into <project_root>/.env (the file is parsed by the copilot route at request time):

# /srv/atlases/my_atlas/.env
ANTHROPIC_API_KEY=sk-ant-...

If you've named the env var something other than ANTHROPIC_API_KEY, match it in stellar.yaml:

modules:
  copilot:
    enabled: true
    anthropic_api_key_env: ANTHROPIC_KEY_PROJECT_X

`anthropic SDK not installed`¶

Symptom

{"detail": "anthropic SDK not installed — pip install 'stellar-atlas[copilot]'"}

Cause — modules.copilot.enabled: true is set but the optional copilot extra wasn't installed.

Fix

pip install 'stellar-atlas[copilot]'

Or, if you don't need the copilot, set modules.copilot.enabled: false in stellar.yaml.

Copilot literature returns 400¶

Symptom

{"detail": "literature not enabled in stellar.yaml — set modules.copilot.literature.enabled: true"}

Cause — the request set include_literature: true but the project didn't opt in.

Fix — enable literature for the project:

modules:
  copilot:
    enabled: true
    literature:
      enabled: true
      scope:
        diseases:   []      # [] = no disease filter
        techniques: [single-cell, snRNA-seq, scRNA-seq, single-nucleus]
        min_year:   2018

Restart the serve process; the tool will be registered with the configured scope.

Enrichment module errors¶

`503 from /api/enrichment` when EnrichR is down¶

Symptom — the Enrichment tab shows an inline error banner; under the hood the route returned HTTP 503 with a message like:

{"detail": "EnrichR upstream: httpx.ConnectError: ..."}

Cause — the EnrichR public API at maayanlab.cloud is unreachable: network outage, EnrichR maintenance, or the host running stellar serve doesn't have outbound HTTPS access.

Fix

Check EnrichR's status: curl -sI https://maayanlab.cloud/Enrichr/
Confirm outbound access from the server (firewall, proxy).
If you need to run fully offline, set modules.enrichment.enabled: false; the SPA hides the tab and the copilot drops the enrich_genes tool automatically.

The route caches identical (genes × libraries) requests in-process for 1 hour, so a transient blip is tolerated for repeat clicks.

Tests / development¶

`tests/test_seurat_io ImportError` on a CI box¶

Symptom

ImportError while loading conftest 'tests/test_seurat_io.py'.

Cause — the Seurat test exercises the subprocess path to Rscript. On a box without R the test is skipped (it doesn't import any R-side Python deps), so any ImportError here points at a missing Python test dep, not R.

Fix — install the dev extra:

pip install -e '.[dev]'

You do NOT need [copilot] — Seurat conversion has no Python deps beyond what's already in the base install.

`mkdocs build --strict` fails¶

Symptom — a WARNING line gets promoted to a fatal error under --strict:

WARNING -  Doc file 'foo.md' contains a link 'bar.md', but the target is not found.

Cause — broken relative link, missing nav entry, or an mkdocstrings ... directive pointing at a Python symbol that doesn't exist.

Fix — fix the link / symbol path. If you've added a new doc page, add it to mkdocs.yml's nav: block too — --strict complains about un-navved pages.

When in doubt — `stellar doctor`¶

Almost every config / data error STELLAR can detect surfaces from stellar doctor:

stellar doctor --config stellar.yaml

It's safe to run anytime. If doctor returns exit code 0 and your problem persists, it's likely a runtime issue (network, key, R) — work back through the sections above.

Troubleshooting¶

Input / config errors¶

FileNotFoundError: Seurat .rds not found or h5ad not found¶

cohort.cell_type_column='cell_type' not in obs¶

Rscript is not on PATH¶

Need either SeuratDisk or sceasy installed in R¶

readRDS produced a SingleCellExperiment object — expected Seurat¶

Build / runtime errors¶

no built atlas yet — run stellar ingest¶

<name>.h5ad is newer than the built DuckDB¶

ImportError: cannot import name 'lance' / Lance ImportError¶

lance.list_tables() error / opening Lance table fails¶

LanceDB / DuckDB version mismatch on import¶

Copilot module errors¶

ANTHROPIC_API_KEY not configured¶

anthropic SDK not installed¶

Copilot literature returns 400¶

Enrichment module errors¶

503 from /api/enrichment when EnrichR is down¶

Tests / development¶

tests/test_seurat_io ImportError on a CI box¶

mkdocs build --strict fails¶

When in doubt — stellar doctor¶

`FileNotFoundError: Seurat .rds not found` or `h5ad not found`¶

`cohort.cell_type_column='cell_type' not in obs`¶

`Rscript is not on PATH`¶

`Need either SeuratDisk or sceasy installed in R`¶

`readRDS produced a SingleCellExperiment object — expected Seurat`¶

`no built atlas yet — run stellar ingest`¶

`<name>.h5ad is newer than the built DuckDB`¶

`ImportError: cannot import name 'lance'` / `Lance ImportError`¶

`lance.list_tables() error` / opening Lance table fails¶

`ANTHROPIC_API_KEY not configured`¶

`anthropic SDK not installed`¶

`503 from /api/enrichment` when EnrichR is down¶

`tests/test_seurat_io ImportError` on a CI box¶

`mkdocs build --strict` fails¶

When in doubt — `stellar doctor`¶