故障排查

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

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:latest

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.

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

“未找到数据集”

Use an absolute path:

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

文件格式无法识别

  • 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

“请先运行预处理”

Most analyses require preprocessing first.

Preprocess the data

“没有显著结果”

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

  • lower significance thresholds

  • try a different analysis method

细胞通讯分析失败

Use species/resource pairs that match the dataset:

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

Resource Problems

系统卡死 / MemoryError

  • subsample data for testing

  • reduce batch sizes

  • monitor memory with top

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

CUDA 显存不足

  • set use_gpu=False

  • reduce batch size

  • clear cached GPU memory if your workflow allows it

Quick Fix Table

问题

First fix

导入错误

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

Docker pull fails

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

Docker dataset not found

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

路径错误

使用绝对路径

Analysis fails immediately

先运行预处理

R 方法失败

Install R and the required R packages

Still Stuck?