Troubleshooting

This page is the canonical symptom → fix guide.

MCP Connection Problems

Tools not showing in the client

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

  2. Confirm the Python path is an absolute path from which python.

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

  4. Restart the client after configuration changes.

  5. Test the server directly:

python -m chatspatial server --help

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

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"

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

Reinstall with uv pip install chatspatial[full]

resolution-too-deep

Use uv instead of pip

Client not connecting

Re-check config and restart the client

Path errors

Use absolute paths

Analysis fails immediately

Run preprocessing first

R methods fail

Install R and the required R packages

Still Stuck?