Troubleshooting
When integrating PATCH some problems may arise. In fact, it interacts with external services like web servers, so sometimes additional operations are needed.
When you contact me to ask for help, please remember to attach:
- Unity Player logs (you can find them here)
- PATCH logs (you can find them in
Logs/folder) - The debug report that PATCH can generate in both Admin Tool and Launcher
Also, try to describe the problem and how you triggered it! Just a simple "it does not work, why?" won't help me to solve your issue quickly!
The Launcher has a Debug Mode that should help with debugging. The Debug Mode can be enabled in two ways:
- building your Launcher in
Debug - set the
UpdatingContext.Settings.DebugModeflag on true - use the settings overrider to override the
DebugModeflag
Debug Mode enables the logging of the Debug level logs, but not only! It also allows you to see additional information about logs like the file from where the log has been sent, the method name, the line number.
Context: the Launcher can self-update to bring to your users new functionalities. But imagine pushing a new Launcher update, so you discover that you introduced a bug that prevents the Launcher from self-updating. Normally this means that the Launcher becomes useless and the final user needs to download manually the fixed Launcher from somewhere. Definitely unpleasant.
The Safe Mode comes in handy exactly in this case. Your users can enable it on their local side by using the settings overriding feature and enabling PatcherUpdaterSafeMode.
When the Launcher runs with this option enabled, it will look at http://RemoteUrl/Updater/updater_safemode_index.json file. You can create the file manually for now. The expected content is:
{
"ArchiveName": "my_safemode.zip",
"ExecutableToRun": "MHLab.Patch.Launcher.Wpf.exe",
}The Safe Mode will download and extract the content of the http://RemoteUrl/Updater/my_safemode.zip archive (so remember to create and upload that archive!) and will remove your old Launcher. When the process completes, the Safe Mode will run the executable stated in the ExecutableToRun field.
You uploaded your files, but the web server seems to not serve them correctly.
By default, web servers do not serve all mime types in production. PATCH tries to use standard data formats for web, but Unity builds can contain a lot of forbidden mime types and the server can block their delivery.
Context: the server returns HTTP errors like 4xx (403, mostly) or 500. You can verify it by navigating to that file's URL with your browser.
Solution: reach your web server's configuration and allow the serving of all mime types. If you are unsure about how to do it, just google the process to do it for your specific web server.
In some cases, your web server may maintain a file cache (in particular if you are using a CDN) to optimize traffic and resource usage.
Context: you modify existing remote files and when you access them through the browser you still see the old version.
Solution: refreshing the cache should solve the problem.
PATCH requires you to set a remote root folder where searching for needed files. If files are not uploaded to the correct location, PATCH cannot find them.
Context: PATCH cannot locate files and/or returns an error like "Our servers are not responding"
Solution: double check your remote folders structure. Your remote folder must have the same structure of PATCHWorkspace folder. Example: your remote folder is http://localhost/patch? PATCH expects to find builds in http://localhost/patch/Builds/, patches in http://localhost/patch/Patches/ and updater in http://localhost/patch/Updater/.
Your launcher downloads the files, but the the update fails or you can't find the downloaded files on your disk.
The Launcher's folder must be writable by the Launcher itself and by the user who runs the Launcher.
Context: the Launcher fails on start and no logs files are generated. This highly suggests that the Launcher and the user have no privileges to create folders and files.
Solution: set write privileges correctly for the Launcher and for the user. If you want to avoid this issue, store your Launcher and your game in a folder that the current user can already write to. For example: C:\Users\myUser\AppData (even known as %APPDATA%). Keep in mind that folders like C:\Program Files are protected/special folders and the current user cannot write there without additional permissions.
Your disk must have available space to download and store new files.
Context: the Launcher complains about not enough disk space. If you disabled the disk space check on the Launcher, the Launcher simply fails to store the files.
Solution: delete files and/or applications from your disk to free up enough space.
Some paths may be too long (in particular on Windows, not sure on other Operating Systems). In particular, Win32 API doesn't support paths longer than 256 characters if the registry flag LongPathsEnabled is not set.
Context: the Launcher fails to store the files and the logs file shows an error that makes clear that the file cannot be stored or that the file cannot be found.
Solution: check the length of your paths and make them shorter. An example of how to measure the path length: C:\MyGame\myfile.txt is 20 characters long and it is valid.
Solution 2: enable the LongPathsEnabled flag on the target system. Follow this article.
When your Launcher starts your game, you are presented with a similar dialog:
Context: you uploaded your files, the Launcher successfully downloaded the files and applied the patches.
Problem description: your game files on your server are corrupted/partially corrupted. This can happen due to multiple reasons, but the most frequent one is: the upload process failed in some point.
Solution 1: check your FTP client's settings and make sure that it transfers files in binary mode and NOT in ASCII or automatic.
Solution 2: try re-uploading everything with a different FTP client. In particular, users using FileZilla experienced this issue more often. Try one of the suggested clients here.