[Addressables] Fix Accentuated Filename Loading Failures in Builds
Solution
Unity 2021.3.x - Unity 6.3.x
Published 28 days ago
Assets containing accentuated characters (e.g., é, à, ü) in filenames fail to resolve via the Addressable Asset System after a build, specifically on Android. This results in a System.Exception: Unable to load asset because the target platform cannot match the encoded file path to the catalog entry, even if your script works in the Editor.
Switch the Internal Id Mode from Full Path to GUID in the AddressableAssetSettings to ensure assets are referenced by their unique identifier rather than literal filenames.
The loading failure occurs because file systems on mobile platforms often handle character encoding differently than the development environment. By default, your script might be using the literal file path as the internal identifier, which breaks when special characters are misinterpreted during path resolution.
To resolve this, follow these steps:
- Select the
AddressableAssetSettingsasset in your project. - In the Inspector, locate the
Internal Id Modeproperty. - Change the value from
Full Pathto GUID. - Open the
Addressables Groupswindow. - Select
Build>New Build>Default Build Scriptto regenerate your catalog with GUID references.
Changing the mode to GUID ensures that the system references the asset by its metadata-linked GUID instead of a string-based file path, making it immune to character encoding discrepancies on various operating systems.
Additional Tips:
- Avoid using special characters in filenames whenever possible to ensure cross-platform compatibility.
- Ensure that the
Include GUIDs in Catalogcheckbox is enabled if you are using manual GUID referencing. - Clear your
Addressablesbuild cache before creating a new build to avoid stale path data.
Related Posts Haven't quite found a solution to your problem? We think these posts might help you.
Content inspired by a Unity discussion post.