Troubleshooting (Web App): Start Here#

This page is a triage map: what you see → what to check → where the real fixes live.

If you can load a demo dataset but not yours, it’s usually data loading / dataset format.

2‑minute triage (do this first)#

  1. Confirm WebGL2 works on this machine: System requirements

  2. Check you’re not in a “looks broken but isn’t” state:

  3. Reload in a clean state (private window; extensions off)

  4. If only one dataset fails, try a known-good demo dataset (if available)

  5. Open DevTools → Console and copy the first error (for bug reports)

Choose your problem (symptom picker)#

What you’re seeing

Start here

App won’t open / blank page / WebGL2 message

Installation & environment

Dataset won’t load / spinner forever / missing embeddings

Data loading failures

Blank canvas after load / “context lost” / choppy FPS

Rendering & GPU issues

Selection tools feel wrong / highlights disappear / counts don’t match

Selection & highlight issues

Analysis is empty / DE or markers look wrong / windows don’t restore

Analysis issues

Export fails / downloads blocked / SVG/PNG looks wrong

Export issues

Community annotation Pull/Publish/consensus issues

Community annotation issues

Deep-dive troubleshooting (where most fixes live)#

Before you assume it’s a bug#

Most “it’s broken” reports reduce to one of these mismatches:

  1. Filters vs visibility: you hid the cells you expected to interact with.

  2. Active view: you’re editing a different panel than the one you’re looking at (live vs snapshot).

  3. Membership vs visibility: highlight pages store membership; filters only change visibility.

  4. Dataset identity mismatch: sessions/annotation won’t apply cleanly to a different dataset export/version.

Installation & environment#

Use this section when Cellucid doesn’t start, your environment blocks required capabilities (WebGL2, file picking, downloads), or you’re running locally and the app won’t boot.

Fast checks

  1. Try a modern desktop browser (Chrome/Edge are often the least frustrating).

  2. Confirm WebGL2 works: System requirements

  3. Try a private window (rules out extensions and stale cached state).

  4. If embedded in an iframe/Jupyter, open Cellucid in a standalone tab (iframes can block file access, pointer lock, fullscreen).

Common symptoms → where to go

Symptom

What it usually means

Where to go

WebGL2 is required but not supported in this browser.

WebGL2 unavailable (device/policy)

System requirements

Blank page or “module script failed to load”

Boot/deployment or local-server issue

Debugging playbook

File/folder picker doesn’t open

Browser restrictions / unsupported file API

Troubleshooting (data loading)

Downloads blocked (“Save State”, “Export”)

Browser download permissions / extension interference

Troubleshooting (sessions) — fast fixes, Troubleshooting (figure export)

If you’re running locally (developer / power user)

Data loading failures#

This is for “my dataset won’t load”, “spinner forever”, “missing embeddings”, or “loaded but missing fields/genes”.

First: identify your loading path

If you’re not sure which applies: Data Loading Overview (All 14 Options).

Fast checks

  1. If demos fail too, this is likely an environment/browser issue → System requirements

  2. If you loaded a large .h5ad directly in the browser, switch to server mode → Server Mode (CLI + Python) — Recommended for Large Datasets

  3. DevTools → Network: look for 404/CORS/timeout errors (don’t guess)

  4. “Loaded but empty” can be filters/visibility → Troubleshooting (filtering)

Go to the deep dive (primary)

Related:

Rendering & GPU issues#

Use this section when Cellucid is slow, the canvas is blank, or you see WebGL-related errors (including “context lost”).

Fast checks (safe first)

  1. Confirm WebGL2 is hardware-accelerated: System requirements

  2. Switch to Points render mode while debugging (smoke + heavy overlays can hide root causes).

  3. Reduce GPU load:

    • clear snapshots (single view),

    • disable heavy overlays (vector fields, bloom),

    • make the window smaller.

  4. If you see “WebGL context lost”: reload, then re-try with reduced load.

Go to the deep dives

If the issue reproduces on a demo dataset (or across multiple datasets), capture a bug report:

Selection & highlight issues#

Selection/highlighting problems are often mismatches between:

  • membership (what a highlight page/group contains),

  • visibility (what filters make visible),

  • and view context (live vs snapshot).

Fast checks

  1. Check Active filters (most “missing highlights” are just hidden): Troubleshooting (filtering)

  2. Confirm the active highlight page and that the group checkbox is enabled.

  3. Confirm you are interacting with the intended panel: View layout: Live + Snapshots (small multiples)

  4. Confirm the tool’s modifier keys (Alt, Shift+Alt, Ctrl/Cmd+Alt).

Go to the deep dives

Analysis issues#

Analysis issues usually come from one of four root causes:

  1. no (or empty) highlight pages/groups to analyze,

  2. confusing visibility (filters) with membership (highlight pages),

  3. missing required data (gene expression, fields),

  4. dataset/session mismatch.

Fast checks

  1. Do you have a non-empty highlight page to analyze? → Highlighting and Selection (Groups, Pages, Tools)

  2. Are you on the view you think you are (live vs snapshot)? → View layout: Live + Snapshots (small multiples)

  3. Does gene search work (if your analysis is expression-based)? → Troubleshooting (fields & legends)

Go to the deep dives

Export issues#

Use this section when exports fail, downloads are blocked, or your PNG/SVG output doesn’t match what you expected.

Fast checks

  1. Export a tiny PNG (e.g., ~600×450 at 150 DPI) to confirm downloads work.

  2. Confirm you are exporting the intended panel (live vs snapshot vs grid view).

  3. Confirm visibility: exporting “0 visible points” produces an empty figure.

  4. If large exports fail, cut size/DPI in half and try again.

  5. Check DevTools → Console for [FigureExport] messages.

Go to the deep dives

Community annotation issues#

This section is for problems in Community Annotation (GitHub sync, Pull/Publish, consensus, “why don’t I see other people’s votes?”).

Fast checks (fixes many reports)

  1. Confirm you are online (annotation is offline-first, but Pull/Publish require network).

  2. Confirm you are connected to the intended repo + branch (teams must agree on this).

  3. Click Pull latest before debugging anything else.

  4. If others can’t see your work: you must Publish (or your PR must be merged).

  5. If you see dataset mismatch behavior, stop and fix dataset identity first:

Deep dives (where the real fixes live)

Related:

Reporting a bug (what to include)#

If you’re asking for help (or filing an issue), include:

  1. Where you ran Cellucid (hosted URL vs local app vs embedded in Jupyter)

  2. Browser + OS (include versions)

  3. Dataset source and loading path (export folder / server mode / Jupyter / GitHub)

  4. Dataset identity (id/fingerprint, if available)

  5. Exact steps to reproduce (numbered; include whether snapshots/filters/highlights were involved)

  6. First Console error + any failing Network request (status code + URL)

Developer-focused capture checklist: