Troubleshooting
===============

For Windows setup, WSL startup errors, missing ROOT libraries, and older
runtime updates, see :doc:`install-windows`. For Linux package/runtime setup,
see :doc:`install-linux`. The sections below cover analysis workflows.

Fit or plot will not start
--------------------------

Check the resolution warning under the run row: it reports runs that cannot
be resolved against the current data tree. In the browser edition, confirm
the server exposes those runs; on the desktop, verify the data directory
preference points at the real data root. If a model has no valid run, the
action reports the reason in the outcome dialog and the run log.

"Nothing to fit"
----------------

An independent-series fit (two or more data sets, no shared parameters) where
every run is set to **skip** reports this instead of running. Set at least
one chip to **reuse** or **refit**, or use **Refit all** from the All
dropdown.

Fitted parameters look wrong or unchanged
-----------------------------------------

* The parameter table is the source of the *starting* values. After a fit it
  holds the fitted results; run the fit again after editing values.
* Hand-edited MSR documents are authoritative: if the editor lock is closed,
  Fit and Plot use the editor text and ignore GUI changes until you unlock
  (see :doc:`msr-editor`).
* A model change rebuilds the parameter table and may reset values; re-check
  the rows for every component you use.

Parameter plot is empty or missing data
---------------------------------------

* Click **Refresh** after a new fit -- panels reread the parameter file.
* Use **Data...** to change the data set of the active panel.
* A panel that shares the X axis with no plottable column shows its empty
  message; activate it and add a parameter or load another file.
* Overlaid files that lack the panel's X column (or could not be re-read)
  are skipped and listed in a striped note under the panel. Fix the X
  column (**X** control) or uncheck the file under **Plot options > Overlay
  data sets**.

Parameter plot hangs on "Preparing plot files"
----------------------------------------------

"Preparing plot files" covers the setup performed before the tools run. If
the step never finishes, check the server/work-bench side:

* The command-line tools must be reachable on the machine that runs them
  (local install on the desktop, server-side install for the CGI).
* On the desktop, confirm the work directory is writable.

The command log records every command line that was attempted; it is the
first place to look.

Web page cannot load data
-------------------------

The browser edition fetches data and runs fits on the server. If the page
loads but actions fail, verify the CGI endpoint is reachable (see
``cgi/README.md``) and that the server data root matches what the page was
deployed with. The server health endpoint reports the configured data root;
muSRFlow's resolution warning should agree with it.

Restored configuration differs from the original machine
--------------------------------------------------------

Configuration links carry analysis settings only, not data or working
directories. On a different machine the same settings resolve against that
machine's data tree. If runs do not resolve, fix the data/startup-XML
configuration (desktop Preferences; server configuration on the web) and
refit.

Some links start with a different prefix
----------------------------------------

muSRFlow shares both a compact compressed form (``#c=``) and a readable
legacy form (``#cfg=``). Both are accepted by the web and the desktop
restore dialog.

Reporting problems
------------------

Include the command log (open from the status bar or the outcome dialog)
and the versions involved. Contact Zaher Salman
`<zaher.salman@psi.ch>`_ with those details for the fastest help.