Troubleshooting

What to do when something does not work, and how to report a problem.

Starting CytoWeave

"command not found"

The installer does not change your PATH on macOS and Linux. If ~/.local/bin is not on it, run the full path, ~/.local/bin/cytoweave, or add the folder to your shell's PATH. On Windows, the installer adds the program to your user PATH, but terminals that were already open keep the old one: open a new terminal.

"cannot be opened" or "Windows protected your PC"

The programs are not signed with an Apple or Microsoft certificate, so a file saved from a browser is flagged on its first start. The installers download without a browser and avoid this. Otherwise, see files downloaded in a browser.

The window does not appear

• CytoWeave opens a desktop app window when Chrome, Edge, Brave or Chromium is installed, and your default browser otherwise. Either way it prints its address, such as http://127.0.0.1:8770: open it in a browser yourself.
• --window browser uses the default browser instead of an app window.
• Closing the window stops the program. --keep-running keeps it serving so you can reopen the address.

Another program uses the port

If port 8770 is taken, CytoWeave uses the next free one and prints it. To choose another, use --port. Running cytoweave while it is already open hands any files to the open window instead of starting a second copy.

Firefox and Safari

CytoWeave is developed and tested in Chrome, Edge and Brave. It uses standard web features only, so current Firefox and Safari should work when you open the address in them, but they are not tested regularly. If something looks wrong in one of them, try a Chromium-based browser before reporting it.

Files

A file will not open

• CytoWeave reads FCS 2.0 to 3.2, and repairs common deviations from the standard (offsets, text encodings, truncated data). Each repair is listed in the Sample section of the inspector. A file that cannot be read is refused with a message saying why: please report it.
• Event data in CSV, imaging flow data (Amnis, CellView) and FlowJo 9 or .flowjo workspaces are not supported. Export FCS, or .wsp from FlowJo 10 or 11.
• Spectral unmixing needs the raw detector channels; files that hold only unmixed channels can be gated but not unmixed again.

Populations lean or look smeared

A population that leans diagonally on a plot of two fluorescence channels usually means a wrong spillover value. Check the matrix the sample uses (inspector, Compensation) and run Check against the controls.

The workspace is not saved

The dot beside the workspace name turns red when saving fails; point at it for the reason. The library must be a folder you can write to, with free space: see the library, or start CytoWeave with --data-dir pointing elsewhere.

A character in a PDF shows as "?" or plain letters

PDF figures and reports set their text in Helvetica, which every PDF reader has without embedding a font. Its character set covers English and Western European text, µ, ×, ±, °, superscript digits and typographic quotes and dashes. Other characters are written as their nearest ASCII (−, ≥ and χ as -, >= and chi) or, without one, as "?". Rename the sample or population, or export the figure as SVG or PNG, which keep every character.

A watched folder does not pick up a file

QC → Live lists files that are still being written under Being written. A file is picked up once its size has stopped changing and its FCS header says all its data are there, so a file whose export was interrupted stays there: export it again. Files that were in the folder before watching began are opened only when you click Check the files already there. Hidden files, names starting with ~ and other extensions (.part, .tmp) are ignored until they are renamed to .fcs. Watching needs the CytoWeave program; it does not work when CytoWeave is served as a plain web site.

Memory and very large samples

Very large experiments are limited by browser memory: about 4 bytes per event per parameter of every loaded sample, plus as much again for the compensated channels in use. Samples load on demand, and the least recently used are dropped beyond 1.6 GB (3 GB on computers with 8 GB of memory or more). If the window becomes slow:

• close other heavy browser tabs;
• avoid Load every sample on very large cohorts, and let samples load as you show them;
• for clustering and maps, embed fewer events per sample.

When the page is served by the CytoWeave program, background analyses share the events with the window instead of copying them. Served as a plain web site, the page is only able to do that if the site sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp; without them, analyses of very large samples (QC of ten million events) can fail.

AI agents

• The agent cannot start CytoWeave. Give the full path to the program in the MCP configuration (~/.local/bin/cytoweave, or %LOCALAPPDATA%\Programs\CytoWeave\cytoweave.exe): agents often start programs without your shell's PATH.
• Proposals or propose_compensation are missing. They need CytoWeave 0.2.0 or later (adapt_gate 0.3.0, check_robustness 0.4.0, the QC, unmixing, clustering, figure, folder, export, template, cell-type and titration tools 0.5.0, compare_distributions, rare_events, add_formula_channel, calibrate_beads, export_report, export_events and differential_analysis 0.6.0, diagnose_unmixing, kinetics, the plate tools and export_workspace 0.7.0, export_certificate, verify_certificate, export_review_report, virtual_fmo, design_panel and check_compensation 0.8.0): check cytoweave --version.
• "The CytoWeave page did not answer in time." Actions run in the window: make sure it is open and not waiting in a dialog.
• A script gets "Opening files needs the X-CytoWeave-Token header". open_files reads from disk, so scripts need the token CytoWeave printed at startup; see Opening files by path.
• The R or Python client cannot find CytoWeave. Start CytoWeave with --remote-control: it then writes remote.json to its data folder, where cw_connect() and cytoweave.connect() look. If CytoWeave runs with --data-dir, set CYTOWEAVE_DATA_DIR to that folder, or pass the address and token CytoWeave printed; see the clients. Use the clients of the CytoWeave version you run (cw_connect() prints it).
• An export says the file exists, or the folder does not. The export tools write only into a folder that exists and never replace a file unless the call passes overwrite: true; scripts also need the token, as for opening files.

Headless runs

• "It needs Chrome, Chromium, Edge or Brave". cytoweave run runs the analysis in a headless browser. Install one of them, or name it with --chrome or the CHROME environment variable (on a server, for example /usr/bin/chromium).
• "Outputs already exist". A run refuses, before it starts, to replace files in the output folder: give --overwrite, or another --output.
• The run exits with status 1. A step failed. run.json in the output folder has each step's message. If the files could not be opened or the template could not be applied, the run stopped there; otherwise the other steps still ran.
• Populations are missing from the results. The template's channels are matched by marker: the apply_template step in run.json lists how each channel matched and which populations could not be applied, with the reason. Check that the files' markers are named as the template's are.

Virtual FMO controls

• "Needs the spread model". The noise is fitted when a compensation is computed from the single-stain controls, or the spreading matrix in Spectral → Panel quality; a matrix from the files or typed in has none. Compute it from the controls (CytoWeave 0.8.0 or later keeps it), and assign it to the samples.
• "Needs an unstained control". Mark a sample's role as unstained; for spectral data, the Spectral view's unstained control is used.
• The real FMO's line is far above the virtual one. The FMO control shows something besides spread: a compensation value that is off (its negative leans against another channel in a pair plot), a reference spectrum that does not match the dye on cells, or nonspecific binding. Check the compensation, or the unmixing with the Spectral view's Diagnose tab.

Certificates

• "Some numbers cannot be computed". Making a certificate reads every sample's file and every channel the analysis stored. Open the missing files again (they are named), or remove the samples, then make it again.
• "The saved comparison … no longer matches the analysis". A gate or an annotation changed after the comparison was saved. The certificate records the numbers the analysis gives now; save the comparison again in Compare so that the Report view cites the same numbers.
• Incomplete. The certificate was made without its FCS files, or some are missing. Supply them (Supply the FCS files…, or --data with cytoweave verify); they are recognized by their checksums, so a renamed file is found, but a file that was changed in any way is not.
• Numbers "equal to 12 significant digits". The certificate was made in another browser version or in Node.js, whose logarithms and exponentials can differ in the last bit; confidence limits and similar numbers then differ in their last digits. They are confirmed; the result names both engines.
• Not confirmed. The result names what differs: a file whose checksum changed (the data are not the ones certified), an edited certificate.json (its fingerprint does not match), a change log altered at an entry, or numbers that differ, with the certified value and the value now. Verifying with another CytoWeave version can also change numbers; the certificate names the version that made it, and every release is on GitHub.

Getting help

Report problems and ask questions on GitHub Issues. Include the CytoWeave version (cytoweave --version, also in the status bar), your operating system and browser, what you did, and what you expected. For a file that does not read correctly, the notes in the inspector's Sample section help most. Do not attach data from patients or anything you are not allowed to share; one of the example experiments often reproduces a problem.