Troubleshooting

Common problems and what to do about them. If yours is not here, the drawer's log (⌘J) often says more, and an issue on GitHub is welcome.

The window closes, or MaveScape says it is already running

• "MaveScape is already running at …": a MaveScape is open; the files you named were handed to it. Switch to its window. Stop it with Ctrl+C in the terminal that started it.
• On macOS, MaveScape keeps serving after you close its window: Chrome (and Edge, Brave) keeps running after its last window closes. If it was already running when MaveScape started, the window opened in it, and MaveScape keeps serving until Ctrl+C. Quit that browser with ⌘Q to have the window's closing stop MaveScape again.
• Another program uses port 8820: MaveScape takes the next free one of the following 19 and prints its address; --port chooses another.
• No window opens: start with --window browser to use the default browser, or --window none and open the printed address yourself.

A table does not open as expected

• No column of variant names is found: choose it in the import wizard. Names must be MAVE-HGVS or a lab form MaveScape reads leniently (Variant names).
• Many names are not valid against the target: check the target and its numbering. A variant named on a reference (residue 159 onward) needs the target's offset, set in the Experiment view.
• A score table, not counts: MaveScape scores from counts. MaveDB offers the counts beside the scores when the authors provided them; showing imported scores on the map comes in 0.3.
• Problems block scoring: the inspector lists them by line (a duplicated variant, a count that is not a number). Fix the table and open it again.

Scoring is refused

The Score view lists every reason. Most often the design has an error (fix it in Experiment), the wild type is not in the table for wild-type normalization (choose another normalization), the wild type or nonsense variants a scale needs are not scored (choose another scale), or the maximum-likelihood fit lacks the bins' gates (give them in Experiment, or score by the weighted average).

A run says its scores differ

When a workspace is reopened, each run is recomputed from its recorded inputs and compared with its recorded output hash. Runs made by MaveScape 0.1.0 used the browser's own logarithms, whose last bit varies between browsers and their versions; recomputed by a later MaveScape, their scores differ only in their last digits, and the run says so. Score again to make a run that reproduces everywhere. A run whose table is not in the workspace cannot be recomputed: open the table again.

Where are my workspaces?

In the library folder the status bar names: ~/Library/Application Support/MaveScape on macOS, ~/.config/MaveScape on Linux and %AppData%\MaveScape on Windows, unless MaveScape was started with --data-dir. Deleted workspaces go to the library's trash folder. To move an analysis to another computer, export the workspace archive (The workspace archive).

Public data are not fetched

• "Public data need the MaveScape program": the page is served as a plain web site; public data come through the program (Getting started).
• "switched off (--no-fetch)" or "running with --offline": MaveScape was started so; with --offline, only copies already in the cache are served. Start it without the flag.
• "Could not reach UniProt" or "did not answer in time": check the network; on one that needs a proxy, set HTTPS_PROXY before starting MaveScape. A copy already in the cache is still used, and the dialog says it is an older one.
• A running MaveScape keeps its own setting: starting mavescape --offline while another is running hands the files to the running one, which says so; stop it first.

Remote control does not answer

• "No MaveScape page is connected": the program is running but no window is open; open the printed address.
• Forbidden: address MaveScape as 127.0.0.1 or localhost, from this computer.
• Unauthorized: open_files and export need the X-MaveScape-Token header with the token from remote.json (Reading and writing files).

mavescape run stops

• Exit 2, "none was found": it runs in Chrome, Chromium, Edge or Brave; name one with --chrome PATH or the CHROME variable.
• Exit 2, "is not empty": the output folder holds files; give another --out, or --overwrite.
• Exit 1: run.json in the output folder lists the problems and each step's outcome: a design that does not fit the table, parameters that cannot score, a quality-control finding that blocks, a run that did not reproduce. mavescape validate shows the same checks without scoring.