Troubleshooting
My track loads but shows no features
The usual cause is a reference name mismatch: the file names its chromosomes
differently than the assembly (chr1 vs 1, or NC_000001.11 vs chr1).
Reference name aliasing
covers confirming that from the "About track" dialogs and mapping the two
schemes together.
Also check:
- the region in view has data at all
- no "Zoom in to see features" message is showing (see the region limits)
A badly bgzipped or indexed file usually throws an error rather than rendering blank. A file the server re-encodes on the way out looks like corruption; see Serving data files.
My tracks are blank or render incorrectly
If menus and track names look fine but features are missing, smeared, or the
wrong color, the drawing path is the likely cause.
&renderer= pins which one is used:
- no parameter - WebGPU-first detection
?renderer=webgpu- require WebGPU?renderer=webgl- WebGL2?renderer=canvas2d- software drawing
On JBrowse Desktop the same choice is the
--renderer flag.
Please open an issue saying which renderer worked, with your browser, operating system, graphics card, and anything the developer console printed.
With many views open, the browser can hit its limit on live WebGL contexts and take one back from a track, shown as a "WebGL context lost" banner. Retry gets it back once another view has freed capacity, and Use Canvas2D switches to software drawing for the rest of the session. Closing unused views also frees contexts.
Why is my track slow
For an indexed file, the time goes into fetching and decoding the region in view. Deep alignment tracks at wide zoom dominate, and CRAM costs more CPU than BAM to decode. The region size gate keeps a wide view from attempting this by accident.
Some adapters read a plain text file with no index (Gff3Adapter, VcfAdapter,
BedAdapter, PAFAdapter) and parse the whole file each time the track loads.
Converting to the bgzip and tabix indexed equivalent, or to
PIF (jbrowse make-pif) for PAF, makes the
cost per-region. The cookbook's
large alignments recipe covers the
synteny case.
Reads are many small range requests, so server latency counts for more than
bandwidth, and a server that ignores Range turns every read into a full
download. See Serving data files.
My setting has no effect
JBrowse ignores a config key it does not recognize, so a misspelled slot loads
and does nothing. jbrowse validate catches exactly that; see
checking a config.
My saved session fails to load
A restored session looks its tracks up by trackId. Changing or deleting one
breaks every saved session that references it, the whole session and not just
that track. See
keeping trackIds stable.
Where can I get help or report a bug
Post questions on the GitHub discussions board or contact us. Report bugs on GitHub issues.