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 `_. 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 ``_ with those details for the fastest help.