Troubleshooting steps

Please consider the following procedure when you encounter a problem you think may be related to the Manager. Only report an issue on GitHub or contact me if you've completed this procedure and the problem did not go away, and the issue has not been reported yet (see the Issues page). You may also report any issues you deem serious or even critical enough that they require my attention.

1. Make sure it's actually a Manager problem and not an 86Box problem

This step generally applies to problems that seem related to virtual machines (ie. they appear "inside" the 86Box window). It may seem obvious to you at first glance, but there were cases where something seemed like a Manager issue, but turned out to be a problem with 86Box itself instead. Not all steps may apply to your particular situation.

If you're not sure, try running 86Box.exe directly with the appropriate -P parameter to start your VM without the Manager. If the problem persists, it's very likely an issue with 86Box, not the Manager, so please report it on the 86Box repo. If the problem goes away, it's likely a Manager problem, so continue with this procedure.

2. Make sure you're using a compatible build of 86Box and have .NET Framework 4.0 installed

The Manager requires 86Box build 1799 or later since version 1.1.0. The reason for this is because earlier builds don't support all the features the Manager expects (ie. the API is not compatible). Therefore, make sure you're using at least build 1799 of 86Box.

.NET Framework 4.0 is required to run Manager at all. If it runs, the problem lies elsewhere, and if you don't have the Framework installed, you'll probably get an error message explaining this to you. But just in case, check if .NET Framework 4.0 is actually installed (not the Client Profile, the full Framework).

3. Make sure you're using the latest available version of Manager

This is a rather obvious step, but there's a chance your problem was already fixed in some newer version of Manager. So don't report issues if you're using an older version and didn't try the latest one.

4. Make sure you've reset your Manager settings

If you're having a problem with Manager settings, you should try to reset them to their default values. Sometimes things just glitch out, and if the problem is gone after this step, it was probably a one-time glitch or something very rare that's hard to pinpoint. If it persists, continue with the procedure.

5. Make sure your folder paths are correct and valid

This applies to VM paths, virtual machines folder and 86Box.exe paths. Make sure the path actually exists (in some cases it should be created automatically by the Manager). If it doesn't, try creating it manually and see if the problem persists.

Also make sure the path does not contain any invalid characters, though Windows should prevent you from using those anyway. Although the Manager supports Unicode characters in paths, it may be worth restricting the character set to ASCII only and changing the path to something else for troubleshooting purposes. Overly long paths should be avoided as well.

You should also try moving the Manager executable (86Manager.exe) to a different folder.

6. Try creating a new virtual machine

If you're having a problem with a particular virtual machine that step 5 didn't solve, you should try deleting the virtual machine but keeping its files, then creating a new virtual machine with the same name. If the problem goes away, it was likely a small glitch not worth debugging, but if it persists, carry on with the steps.

7. Try deleting the 86Box registry key

Please note: this step should be performed only if you know how to work with the Windows registry and Registry Editor. Otherwise, skip this step to avoid causing any potential damage to your machine.

Also be aware that this step will reset all your Manager settings and delete all your virtual machines, though their files will remain in the virtual machines folder.

First make sure the Manager is not running when performing this step. Then open up the Windows Registry Editor (REGEDIT.EXE) and confirm any security prompts that may appear. In the tree view on the left, navigate to Computer\HKEY_CURRENT_USER\Software\86Box. Make sure you've selected the 86Box key, then right-click on it and select "Delete". Click "Yes" once the warning appears, then close the Registry Editor.

You can now start the Manager again. You should be informed that the settings are missing and you'll be asked to configure them now. Once you've done so, you can readd any virtual machines you've had before by setting the same names as before.

8. See if your issue was already reported

Have a look at the Issues page here on GitHub and see if anyone reported a similar or identical issue before. If so, try following any potential troubleshooting steps in that issue before you submit a new one.

What now?

If you've tried all of the steps above and your problem is still not solved, you may submit a new issue here on GitHub or contact me (see README.MD for contact details). And as said at the start of this page, feel free to report any issues you deem serious enough to require fixing, especially if they involve data loss or they prevent you from using the Manager normally.