Skip to content

Troubleshooting

Jump to bottom
Eric Cramer edited this page May 28, 2026 · 1 revision

Troubleshooting

Common errors and how to fix them. If you hit something not listed here, please open an issue.

plot_surface raises a color-shape / broadcasting error

Symptom: matplotlib 3.3+ rejects the color array shape that TissueSection.visualize() (or the GUI's 3D viewer) passes to Axes3D.plot_surface.

Cause: older calling code passed a single RGBA tuple where matplotlib now wants an (N, M, 4)-shaped facecolors array matching the surface mesh.

Fix: the package builds the color array with np.tile(color, x.shape + (1,)) so the dtype/shape match matplotlib's expectation. If you maintain a fork and see this error, ensure the surface-plotting block uses that pattern (or upgrade to v0.1.0+). Reference: the maintainer note bundled under docs/notes/plot-surface-bug.md in the source tree.

MCP server doesn't appear in Claude Desktop

Symptom: Claude Desktop starts but the tissue-simulator MCP tools aren't available; logs show "transport error" or "command not found".

Causes and fixes:

  1. Relative path in claude_desktop_config.json. Always use absolute paths for both the Python interpreter and the script. The example config in docs/guides/mcp.md uses absolute paths intentionally.
  2. mcp package not installed. It's an optional extra: pip install -e ".[mcp]".
  3. Wrong Python interpreter selected. If you use a venv or conda env, point the config's command at that interpreter (e.g. /Users/you/miniforge3/envs/tissues/bin/python), not the system one.
  4. Stale tool cache in Claude Desktop. Quit and relaunch the app after editing the config — it doesn't hot-reload.

"NetworkX not installed" error from spatial-analysis / graph-coloring / replicate-generation

NetworkX is required for those three subsystems but not for basic tissue generation. Install via:

pip install networkx
# or pull it in with the dev / mcp extras: pip install -e ".[mcp]"

The package guards each subsystem with a NETWORKX_AVAILABLE flag and warns on import when it's missing.

generate_cells() returns 0 (no cells placed)

The RSA packer stops after max_attempts consecutive failed placements. Returning 0 means it couldn't fit a single cell, which is almost always one of:

  1. max_attempts too low for the radius mix. Default is 1000. For larger tissues or tighter min_spacing, raise to 5000–20000.
  2. Cell radii larger than (or comparable to) the tissue dimensions. Confirm cell_radii is in micrometers and consistent with height/width/thickness.
  3. allow_boundary_cells=False with a small tissue. Cells must fit entirely inside the bounds — combined with min_spacing, this can shut out large cells. Try allow_boundary_cells=True.
  4. min_spacing too large. It's a surface-to-surface gap; min_spacing=10.0 on cells of radius 5 effectively reserves a 30µm exclusion zone per cell.

Replicate divergence reported as nan

Symptom: ReplicateStatistics.divergence_score is nan for replicates that look fine visually.

Cause: nan means the JS-divergence comparison had no signal to compare — typically because the target's interaction set is empty. This commonly happens when network_mode="contact" is used on a packed tissue: packing uses min_spacing > 0 so surface contacts are rare and the contact-mode network is empty.

Fix: use network_mode="radius" with an explicit network_radius (e.g. 20.0) for both the target-stats extraction and the ReplicateGenerator constructor. This matches what the existing tests do. See the v0.1.2 changelog entry for the nan-on-no-signal semantics.

Clone this wiki locally