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.

Not all steps may apply to your particular situation. Also consider that if you encounter problems while making your own changes to the code, I am not obligated to help you fix them unless the problem originates from the main repo (ie. my code).

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.

If you're not sure, try running 86Box directly with the appropriate -P command line argument 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.6 installed

86Box Manager 1.6.1 or later requires 86Box 2.07 or later. The reason for this is because earlier builds of 86Box don't support all the features the Manager expects (ie. the API is not entirely compatible). Although earlier builds will probably work as well to some extent, any issues coming from an unsupported configuration will be ignored.

.NET Framework 4.6 is required to run the Manager. 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.6 is actually installed. Download link is in the README.

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

This is a rather obvious step, but there's a chance your problem was already fixed in a newer version of Manager (if it is available). So don't report issues if you're using an older version and didn't try the latest stable one. If you're using a pre-release version, consider going back to the latest stable version in case the problem appeared after that.

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 can simply 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, the virtual machines folder, and 86Box.exe paths. Make sure the path actually exists (it should be created automatically by the Manager). If it doesn't, try creating it manually and see if the problem persists. Depending on your Windows configuration, you may need to adjust user permissions on these folders to allow the Manager to work properly.

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, removing any spaces or other special characters, and changing the path to something else for troubleshooting purposes. Overly long paths should be avoided as well.

You can 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, 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 the 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 their respective folders.

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, you may reconfigure them however you like. 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. Try following any potential troubleshooting steps in that issue, if that does not work you may comment on the existing issue to confirm you are having the same or a similar problem. Please don't create duplicate issues.

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.