Troubleshooting

The download is blocked

Microsoft Edge holds the installer back with “isn’t commonly downloaded”. The file is not saved until you keep it: in the downloads panel open the file’s … menu → Keep, then choose Keep anyway — it is under the ⌄ arrow beside the Delete button. The confirmation names the publisher, KeyQ, Inc. See Install.

A script or curl gets rejected. The filenames contain a space; the URL must be percent-encoded (%20).

Windows says the publisher is unknown

Expected on a new product. The installer is signed — SmartScreen reputation accrues with install volume and a recent release has not accrued it yet. More info → Run anyway. See Install.

My license file does not appear in the picker

Older builds filtered the file picker to .json only, which made a license with a different extension invisible rather than rejected — nothing to click and no explanation.

Rename the file so it ends in .json. The extension is cosmetic; the app verifies the contents and the signature, not the name. Current builds accept both extensions and offer an all-files option.

Gating, export or AI is refused

That is the license boundary. Viewing always works; editing, exporting and AI need an active license. The message names which of the three was blocked and whether the license has expired or was never installed — read it rather than guessing, because “expired” and “never heard of you” need different fixes.

A population is smeared against the axis, or has vanished

Almost always the scale, not the gate and not the compensation.

Compensated data contains negative values. A log axis cannot display them, so a real negative population piles against the axis or disappears. Switch that axis to logicle, asinh or hyperlog.

AI-1 declines everything, or declines a population I clearly have

Check channel names first. AI-1 identifies channels by the marker they measure, not by fluorochrome or channel order — a channel called FL4-A with no marker name is invisible to it. Name your markers in the parameter editor and run it again.

If names are right and it still declines, read the competence report. Three distinct things cause a decline, and they need different responses:

• The marker is not in the panel — nothing to do; the call is not possible.
• The population is out of repertoire — AI-1 covers a published list, human samples only. Gate it by hand or use the copilot.
• The data looks unfamiliar — a different instrument or protocol than it was trained on. Its ranking may still be useful but its thresholds are not calibrated for your data.

Also confirm the sample is human. On mouse data the model separates populations well and calibrates disastrously, which is exactly why it refuses rather than reporting a number.

Statistics are not what I expect

Check what the percentage is a percentage of. A population’s frequency is a percentage of its parent, not of all events. Look at the breadcrumb above the plot and the population’s place in the hierarchy. See Statistics.

A workspace opens with missing files

The workspace references your FCS files rather than copying them, so moving or renaming the data breaks the link. The app asks you to relocate them. See Workspaces.

Compensation looks wrong after I changed it

Gates are regions in a coordinate space. Change the compensation underneath and the events inside a gate can change. Compensate first, then gate — and if you must change it afterwards, check every gate.

Each file has its own compensation, and an edit changes only the active file. Check the badge beside each file: Comp (its own acquisition matrix), Comp* (a different matrix), Comp ⚠ (the matrix does not fit the file, so it cannot be counted). To give several files the same matrix, use Apply to all open files. See Compensation.

The local AI

The NVIDIA engine needs repair

Preferences → AI → Local LLM says “Not running — the engine needs repair”: the NVIDIA CUDA engine is missing NVIDIA’s runtime files, so it cannot use the GPU. Engines installed by versions before 0.2.0 were downloaded without them.

Click Repair. It downloads only those files (about 373 MB); the engine and your models stay as they are, and the screen then reads “NVIDIA runtime installed.” If you cannot download them now, Run on CPU for now keeps the local model working without the GPU.

Is the local model really using my GPU?

The same screen shows what the engine is running, read from the engine itself — for example “29/29 layers on the GPU”, with the context size, cache type and flash attention. That is the reliable check.

In Windows Task Manager, the GPU graph shows 3D by default, which stays low while a model runs. Choose Cuda from the graph’s drop-down to see the engine’s activity.

High CPU use while the assistant works

The gating model (AI-1) runs on the CPU by design. When the assistant uses it — or you click Run it — the CPU stays busy for a few minutes on a large file while a progress card shows the elapsed and estimated time. That is expected, and does not mean the language model has left the GPU. Within a session the assistant reuses a file’s result rather than running the model again; see AI-1.

Settings stays on “Detecting hardware…”

In 0.2.0, on some computers with Intel or AMD graphics (no NVIDIA GPU), the hardware check behind Preferences → AI → Local LLM never finished, and the built-in engine could not be set up or used. Fixed in 0.2.1 — update from the in-app prompt or the download page. Ollama and the cloud providers were never affected.

A large file is slow

A million events is normal. Opening one takes seconds; running AI-1 over it takes a few minutes, longer on a slower computer.

The progress card shows an estimate for your machine, learned from your own completed runs. On the first run it has nothing to learn from, and on a slow or heavily loaded computer it can be passed before the run finishes. Watch the elapsed counter: if it is still climbing, the model is working, not stuck.

On a computer without graphics acceleration — a virtual machine, a Remote Desktop session, or a disabled graphics driver — versions before 0.2.2 used a lot of CPU just to keep an open plot on screen, which slowed AI-1 considerably. Fixed in 0.2.2 — update.

Still stuck

Help → Report an Issue (the ? icon in the toolbar) opens a new email to [email protected] in your mail program, with a short template asking for your version (Help → About Cytogence), your operating system and what happened. Nothing is sent until you send it, and nothing is attached — read it before sending, and leave out sample names and file paths, because sample identifiers live in filenames.

If we need a screenshot or a sample to reproduce something, we ask you directly and tell you what is safe to send.

If the machine has no mail program set up, email [email protected] from another one with the same details.