Troubleshooting

This page is the canonical symptom → fix guide.

Diagnosis Order

Start with the earliest layer that could be broken:

  1. Client connection — the MCP tools do not appear or the server cannot start.

  2. Runtime paths — the server starts, but data or output paths are not visible.

  3. Data loading — the file is visible, but the format or folder layout is wrong.

  4. Analysis prerequisites — the data loaded, but a downstream method is missing preprocessing, metadata, or optional dependencies.

  5. Resources — the analysis is valid but runs out of memory, GPU, or time.

MCP Connection Problems

Tools not showing in the client

  1. Confirm you used the correct config file for your client.

  2. For the recommended setup, confirm uvx --version works in a new terminal.

  3. Check the config file for JSON/TOML syntax errors.

  4. Restart the client after configuration changes.

  5. Test the server directly:

uvx --from chatspatial chatspatial --version

If you need the exact config file format, go back to the Configuration Guide.

“python not found” or “module not found”

  • Make sure ChatSpatial is installed inside the environment you configured

  • Re-run which python inside the activated environment

  • Update the MCP config to use that exact path

uvx not found

  • Install uv using the official installer, then open a new terminal.

  • Confirm uvx --version works from the same environment that launches the MCP client.

  • On desktop clients, restart the application so it reloads PATH.

First launch is slow

The first uvx launch downloads and installs the core scientific Python stack into an isolated cache. Later launches reuse it. Run the following once in a terminal to warm the cache and surface installation errors directly:

uvx --from chatspatial chatspatial --version

Docker / GHCR Problems

docker: command not found

Install Docker Desktop or Docker Engine, confirm docker --version works, then restart your MCP client.

Pull fails for the GHCR image

Check the image name and network access:

docker pull ghcr.io/cafferychen777/chatspatial:v1.5.3

MCP tools do not appear when using Docker

  • Use --rm -i, not -it, in MCP stdio configuration

  • Use absolute host paths in -v mounts

  • Restart the MCP client after changing configuration

Dataset not found in Docker

Mount the host data directory and use the container path in prompts:

-v /Users/alice/spatial-data:/data:ro

Load /data/sample.h5ad

Do not prompt with /Users/alice/spatial-data/sample.h5ad; that path exists on the host, not inside the container. The full Docker mount model is maintained in Docker / GHCR.

Permission denied on mounted outputs

Confirm the host output directory exists and Docker has permission to write there. On Docker Desktop, also check file-sharing permissions for the mounted parent directory.

Data Loading Problems

“Dataset not found”

Use an absolute path:

❌ ~/data/sample.h5ad
❌ ./data/sample.h5ad
✅ /Users/yourname/data/sample.h5ad

File format not recognized

  • H5AD: verify with python -c "import scanpy as sc; sc.read_h5ad('file.h5ad')"

  • Visium: point to the directory containing the spatial/ folder

  • HDF5 check: file yourdata.h5ad

Analysis Problems

“Run preprocessing first”

Most analyses require preprocessing first.

Preprocess the data

“No significant results”

  • check data quality (>500 spots, >1000 genes)

  • lower significance thresholds

  • try a different analysis method

Cell communication fails

Use species/resource pairs that match the dataset:

For mouse: species="mouse", liana_resource="mouseconsensus"
For human: species="human", liana_resource="consensus"

LIANA is the default. FastCCC and CellPhoneDB currently accept human data only. If FastCCC is missing, install chatspatial[fastccc]; do not install the old upstream fastccc distribution beside it.

FastCCC and CellRank appear to conflict

Use ChatSpatial 1.3.8 or newer and resolve both from ChatSpatial’s extras in a fresh environment:

python3.12 -m venv chatspatial-clean
source chatspatial-clean/bin/activate
uv pip install 'chatspatial[fastccc,trajectory]'
uv pip check

The maintained FastCCC distribution has no Jinja2 dependency. pyGPCCA may still select Jinja2 3.0.3 because of historical package metadata, but it does not use Jinja2 at runtime, so no manual override is needed. If pip check mentions the distribution named fastccc rather than fastccc-modern, the old package is a residue from a previous environment; reproduce the installation in a clean side-by-side environment instead of deleting packages from the old one.

An optional method is not installed

Install the method family named in the error, or use full for every composable Python family:

uv pip install 'chatspatial[full]'

full intentionally excludes R bridges, AESTETIK, and rctd-py. See Installation before adding those isolated extras.

Resource Problems

System freezes / MemoryError

  • subsample data for testing

  • reduce batch sizes

  • monitor memory with top

  • use 32GB+ RAM or cloud resources for large datasets

CUDA out of memory

  • set use_gpu=False

  • reduce batch size

  • clear cached GPU memory if your workflow allows it

Quick Fix Table

Problem

First fix

Import errors

Reproduce in a fresh environment with uv pip install 'chatspatial[full]', then run uv pip check

resolution-too-deep

Use uv instead of pip

Client not connecting

Run the configured uvx command in a terminal, then restart the client

Docker pull fails

Run docker pull ghcr.io/cafferychen777/chatspatial:v1.5.3 and check network access

Docker dataset not found

Mount the host data directory and prompt with /data/...

Path errors

Use absolute paths

Analysis fails immediately

Run preprocessing first

R methods fail

Install R and the required R packages

Still Stuck?