Troubleshooting

Version Processing Errors

When you upload a new version, PatchKit processes the ZIP archive before it can be published. Processing can surface errors (blocking publication) and warnings (non-blocking, but worth reviewing). The messages below are the most common ones you will hit on a first publish.

Before you upload: ZIP requirements

• The archive must use STORE or DEFLATE compression. DEFLATE64 is not supported and the upload itself will be rejected.
• Your game’s top-level directory goes inside the ZIP — PatchKit will detect a single top-level subdirectory and flatten it (you will see the Subdirectory moved one level up info message).
• File names must use ASCII characters only. Backslashes (\) in file names also cause problems on some platforms.

Missing executable file

PatchKit could not find a launchable executable (e.g. .exe on Windows, a binary with the exec bit on Linux/macOS) in your content.

• Verify that the executable is present inside the ZIP and that its name is not filtered out by your build system.
• On Windows, confirm the .exe extension is lowercase.
• After re-uploading, check the Executable File field on the version’s page — if PatchKit guessed wrong you can set it manually.

Invalid encoding filenames found

One or more files contain non-ASCII or special characters (or a backslash) in their names. The error message lists the offending files.

• Rename the files in your build pipeline so only ASCII characters are used.
• Avoid \ in file names, even on Windows.

One of uploaded files is too big

A single file exceeds the per-file size limit. The message names the file and the limit.

• Split the file, or consider whether the asset should really be shipped with the build.
• If you believe the limit is incorrect for your case, contact support.

Subdirectory moved one level up (info, not blocking)

Your files were uploaded inside a subdirectory (e.g. MyGame/game.exe). PatchKit automatically moved them up one level. This is fine — it just lets you know the flatten happened.

Found files created for other platforms (warning)

PatchKit detected files that look like they belong to a different platform than the Application is configured for (e.g. Windows .dll files in a Linux build). Double-check your build output before publishing; the version will still be publishable.

Resulting patch file size is suspiciously big (warning)

The generated delta patch is nearly the same size as a full content download. This usually means the new version shares little with the previous one — a renamed root directory, a rebuild with different timestamps, or an unrelated build uploaded by mistake. Review your files before publishing to avoid shipping a huge update to players.

Found app_data.json / Unity output_log.txt has been found (info, auto-removed)

These files are generated by the launcher on the user’s machine and must not be part of your distribution. PatchKit removes them automatically — but clean them up in your build pipeline so the warnings stop appearing.

Found banner file (error, blocks publish)

PatchKit detected a banner file in your content’s root directory. Banner files are created by the launcher on the user’s machine and must not be shipped inside your build. Remove the file from your build output and re-upload the version before it will be publishable.

Launcher content errors (custom launchers only)

When you upload a custom launcher (Unity or Electron) rather than game content, additional errors can appear:

• Patcher manifest not found — the patcher.manifest file is missing. For the Unity launcher, this is produced by Tools → Build in the Unity editor.
• Missing electron zip file / Missing electron executable file — the inner ZIP structure of an Electron launcher build is not as expected. Rebuild using the SDK’s publish flow.
• Invalid OSX minimal version — the macOS build’s Info.plist declares a minimum OS version that PatchKit cannot handle.

If you see an error that is not listed here, use Contact Support from the version’s page — the full processing log will be attached automatically.

Launcher Troubleshooting

PatchKit desktop applications are built on fail-safe architecture principles, but there are several cases where things may go wrong during the initial installation or patching stage. This page will outline the most common issues your users may encounter and their possible solutions.

Downloading Issues

Downloading issues are the most common problems that users face when using PatchKit. Despite improvements in worldwide Internet infrastructure, several factors may slow down or prevent the user from downloading the application.

Possible Reason: ISP Hardware Issues

The first step in resolving this issue is to check the quality of the user’s internet connection. While speed tests can be useful, some ISPs are known to configure routing rules to popular speed test sites to give better-than-usual results.

• Ask the user to visit https://speed.cloudflare.com/ and see if the results to their nearby servers are looking good.
• Ask the user to perform a ping test on this page: https://freeola.com/line-test/. A high jitter or packet loss value may be the reason.
• If the user has a secondary internet connection, it should be examined.

Possible Reason: Wi-Fi

Wi-Fi hardware often causes trouble. It’s hard to find a router that does not need to be reset once in a while. Ask the user to try resetting the Wi-Fi router in use. Connecting via a cable connection is also recommended.

Possible Reason: Routing Issues

When connecting from point A to B, there are plenty of cables and hardware in between. The routing configuration of each of those decides where the connection should go through, and sometimes it may go through a sub-optimal route. It can even fall back to a slower route due to incidents like a power outage at a strategic point.

• Ask the user to perform a benchmark to see if there are any problems.
• Ask the user if the problem affects other services. If it does, the user should contact their ISP.

Possible Reason: Malicious or Packet Inspection Software

In some configurations, software that tampers with the Internet connection may slow it down or prevent the user from downloading specific data.

• Ask the user to try installing the application on another machine or operating system if possible.
• Ask the user to perform an anti-virus scan and anti-malware scan. We recommend Malwarebytes scanning software.
• Ask the user to disable the anti-virus during the downloading procedure.

Possible Reason: Firewall Configuration

Depending on the user’s machine, there may be a firewall installed with rules that effectively prevent downloading data from untrusted sources.

If the user is trying to install the software:

• On a home PC, we suggest disabling the firewall.
• At the workplace, we suggest contacting the administrator.
• At school, we suggest contacting the teacher or the administrator.

Possible Reason: Missing Certificates

PatchKit uses HTTPS to secure the connection between the user and the server. If the user’s machine is missing the necessary certificates, the connection may be blocked. We primarily use AWS-issued certificates, which should be present in most operating systems, but in some cases, they may be missing.

The most common indicator of a missing certificate is an almost immediate API connection error after the launcher starts.

To fix this issue, the user should:

1. Go to https://www.amazontrust.com/repository/.
2. Download the DER format of the Starfield Services Root Certificate Authority - G2 certificate (link).
3. Install the certificate in the operating system’s certificate store by right-clicking on the file and selecting Install Certificate.
4. Restart the launcher.

Nothing Helps?

If the user has tried everything and the issue persists:

1. Ask for launcher-log.txt and output_log.txt files. Check here for the Basic (Unity) launcher and here for the SDK launcher to find those.
2. Contact PatchKit’s support by e-mail, providing all files mentioned above, along with the user’s PatchKit account e-mail address and application name.

Installation / Patching Issues

The PatchKit packages are encrypted, compressed packages that need to be decrypted, unpacked, and saved to the disk drive. This process is called the installation process, and there are several places where it can fail.

Possible Reason: Anti-Virus Software

Anti-virus software is meant to protect the user from installing any malicious software, but it can act overly cautious with launchers. While our launcher does its best to co-exist with most anti-viruses, it can still conflict with some of them.

Ask the user to disable the anti-virus software during the installation process.

Possible Reason: Malicious Software

Malicious software can hook into system events in a similar manner to anti-virus software. These are often poorly written and may tamper with the operating system’s stability.

Ask your user to perform a system scan using Malwarebytes free scanner.

Possible Reason: Hardware Issue

Faulty hardware like a hard disk, RAM, or even the CPU can affect the installation process. Ask the user if there were any strange issues with the PC lately. We recommend reading this article.

Nothing Helps?

If none of the above helps, follow these steps:

1. Ask for the launcher-log.txt and output_log.txt files. Check here for the Basic (Unity) launcher and here for the SDK launcher to find them.
2. Contact PatchKit’s support by e-mail, providing all the files mentioned above, along with the user’s PatchKit account e-mail address and application name.

Application Running Issues

If the installation goes smoothly, but the application does not start, don’t panic. These issues are usually easy to solve.

Possible Reason: Wrong Executable File

When your game is first uploaded, PatchKit tries to guess which executable file is the main application file. Make sure to verify it.

1. Navigate to https://panel.patchkit.net.
2. Log in to your account if needed.
3. Navigate to your application’s latest published version.
4. Check if the Executable File is set correctly.

Possible Reason: Missing Application Files

While the launcher makes sure that all provided files are installed on the system, sometimes the application package may be incomplete. The usual reason is a human mistake during the packaging process. Make sure to:

• Zip the whole folder with the application. It’s okay to have one directory at the top-level, with an application executable in that directory.
• Use continuous-integration tools whenever possible. We recommend integrating with pkt as well.

Possible Reason: Anti-Virus Quarantine

Sometimes, anti-virus software can quarantine your game files, restricting any access. Ask your user to disable anti-virus software before running your application. If it doesn’t help, ask the user to check the quarantine list.

Possible Reason: Malicious Software

Because of the variety of this kind of application, there is a possibility of interference. Ask the user to scan the system. We recommend using the Malwarebytes scanner.

Nothing Helps?

There may be plenty of reasons why your application may not be working correctly. If you have tried everything, look for any error messages and search them on the web. You can always contact our support for advice.