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

For initial package setup, see :doc:`installation`. The sections below cover
platform failures and analysis workflows.

Windows and WSL
---------------

Required feature is not installed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``HCS_E_SERVICE_NOT_AVAILABLE`` means Windows could not create the WSL virtual
machine. In **PowerShell as Administrator**, enable the required feature:

.. code-block:: powershell

   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart Windows. Check **Task Manager / Performance / CPU** for
**Virtualization: Enabled**; if disabled, enable hardware virtualization in
BIOS/UEFI. A virtual-machine host must expose nested virtualization. If the
error persists, check the boot setting:

.. code-block:: powershell

   bcdedit /enum | findstr -i hypervisorlaunchtype

Only if it reports ``Off``, run ``bcdedit /set hypervisorlaunchtype Auto`` and
restart. See `Microsoft's WSL troubleshooting guide
<https://learn.microsoft.com/en-us/windows/wsl/troubleshooting>`_.

Cannot find wsl.exe
~~~~~~~~~~~~~~~~~~~

For ``spawn wsl.exe ENOENT``, check that ``wsl --version`` works in PowerShell,
install the current muSRFlow release, and confirm the selected work directory
exists and is writable.

Cannot load libCore.so
~~~~~~~~~~~~~~~~~~~~~~

Install the current muSRFlow release, which supplies the ROOT library path to
every bundled command. A Windows ``ROOTSYS`` or ``LD_LIBRARY_PATH`` setting is
not a substitute for the WSL launcher configuration.

Missing boost/version.hpp or plotting crash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Older imported runtimes may need ``boost-devel``. Follow
:ref:`windows-existing-installations` to repair one in place. Fresh runtime
bundles include it.

No spectrum window appears
~~~~~~~~~~~~~~~~~~~~~~~~~~

Confirm that ``wsl --version`` lists WSLg, run ``wsl --update``, and inspect
the muSRFlow command log. A successful fit does not by itself verify WSLg.
When reporting the problem, include the application version, full log, and:

.. code-block:: powershell

   wsl --version
   wsl --status
   wsl --list --verbose

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.
