-
Notifications
You must be signed in to change notification settings - Fork 45
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).
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.
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
.
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.
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.
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.
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.
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.
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.
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.
Copyright © 2018-2020 David Simunič. All rights reserved.
See the LICENSE
file for license information and AUTHORS
for a complete list of contributors and authors.