Android packaging fails with "cannot find symbol: class DownloadShim" when the package name's second segment is "EpicGames" — UBT cleanup deletes DownloadShim.java on Windows

General Issues and Bug Reporting (Unreal Engine)
, ,
1

Summary

On Windows, packaging for Android fails when the Android package name’s second segment is “EpicGames” (any casing), e.g. com.EpicGames.AndroidQuickStart — the exact example used in the official Android Quick Start documentation. The Gradle task :app:compileDebugJavaWithJavac fails with “cannot find symbol: class DownloadShim” because UBT’s cleanup logic deletes the freshly generated DownloadShim.java. Root cause: UBT writes the shim to the lowercase hardcoded path Build/Android/src/com/epicgames/unreal/, which NTFS (case-insensitive) resolves into the com/EpicGames/ directory already created from the package name; the cleanup pass then compares paths case-sensitively, fails to recognize the file as the shim, and deletes it.

Root cause in UEDeployAndroid.cs (MakeApk):

  1. Based on the package name, UBT creates the template directory Build/Android/src/com/EpicGames/AndroidQuickStart/ first, so the “com/EpicGames” directory exists on disk with that casing.
  2. WriteJavaDownloadSupportFiles then writes DownloadShim.java to Build/Android/src/com/epicgames/unreal/ (lowercase, hardcoded). On NTFS this path resolves into the already-existing com/EpicGames directory, so the file physically lands at com\EpicGames\unreal\DownloadShim.java.
  3. The subsequent cleanup loop keeps the shim only when filename == UnrealDownloadShimFileName. This is a case-sensitive ordinal comparison: the enumerated path (com\EpicGames...) does not equal the expected path (com\epicgames...), so the freshly written shim is deleted as a leftover file.
  4. Gradle then compiles app/src/main/java/com/epicgames/unreal/GameActivity.java, which unconditionally imports com.epicgames.unreal.DownloadShim (line 217 of the template), and javac fails with “cannot find symbol”.

Evidence from the UAT log (consecutive lines, same run):

==== Writing to shim file C:[Project]\Build\Android\src\com\epicgames\unreal\DownloadShim.java ====
Cleaning up files based on template dir C:[Project]\Build\Android\src\com\EpicGames\AndroidQuickStart
Cleaning up file C:[Project]\Build\Android\src\com\EpicGames\unreal\DownloadShim.java

Suggested fix: perform the shim/OBBData path comparisons case-insensitively on Windows (e.g. StringComparison.OrdinalIgnoreCase), or exclude DownloadShim.java from the cleanup set entirely.

Verified workaround: change the package name so its second segment is not “EpicGames” in any casing (e.g. com.MobileTestGame.Game), delete Build/Android and Intermediate/Android, then repackage — the build succeeds.

What Type of Bug are you experiencing?

Documentation

Steps to Reproduce

  1. On a Windows machine, install UE 5.8.2 via the Epic Games Launcher and set up the Android toolchain via Turnkey (Platforms > SDK Management > Android > Install SDK; NDK r27c).
  2. Create a new Blueprint project with Target Platform = Mobile (any template, e.g. TopDown).
  3. In Project Settings > Platforms > Android > APK Packaging, set Android Package Name to com.EpicGames.AndroidQuickStart — the example shown in the official Android Quick Start documentation.
  4. Package the project: Platforms > Package Project > Android > Android (Multi: ASTC, DXT, ETC2).
  5. Cooking and .so compilation succeed, then the build fails in the Gradle step.

Expected Result

Packaging succeeds regardless of the package name casing. UBT’s cleanup pass should recognize DownloadShim.java as the shim (case-insensitive path comparison on Windows) and keep it, so :app:compileDebugJavaWithJavac compiles GameActivity.java without errors.

Observed Result

The Gradle build fails:

Task :app:compileDebugJavaWithJavac FAILED
Z:\app\src\main\java\com\epicgames\unreal\GameActivity.java:217: error: cannot find symbol
import com.epicgames.unreal.DownloadShim;
^
symbol: class DownloadShim
location: package com.epicgames.unreal
1 error

FAILURE: Build failed with an exception.

  • What went wrong:
    Execution failed for task ‘:app:compileDebugJavaWithJavac’.

Compilation failed; see the compiler output below.

Followed by:
UATHelper: Error: cmd.exe failed with args /c “[Project]\Intermediate\Android\arm64\gradle\rungradle.bat” :app:assembleDebug
AutomationTool exiting with ExitCode=1 (Error_Unknown)
PackagingResults: Error: Unknown Error

The UAT log shows that UBT wrote DownloadShim.java and then immediately deleted it in its cleanup pass; the two paths differ only in the casing of “EpicGames”.

Affects Versions

5.8

Platform(s)

Android

Additional Notes

  • Environment: Windows host, UE 5.8.2 Launcher build (5.8.2-56702186), NDK r27c, Gradle 8.13, Android (Multi: ASTC, DXT, ETC2), Development config, Blueprint project. SDK validation passed (platform buildable: True), so this is unrelated to SDK setup.
  • The official Android Quick Start guide (Android Quick Start | Unreal Engine 5.8 Documentation | Epic Developer Community) uses com.EpicGames.AndroidQuickStart as its example package name, so any Windows user following the documentation will hit this failure.
  • Relevant source: Engine/Source/Programs/UnrealBuildTool/Platform/Android/UEDeployAndroid.cs, cleanup loop in MakeApk (if (filename == UnrealDownloadShimFileName) continue;).
  • Suggestion: besides fixing the comparison, consider updating the documentation example to an all-lowercase package name (Java convention) so users are not led into this trap.
  • Only verified on 5.8.2; the same comparison pattern may exist in earlier 5.x releases but was not tested.