UnityRef is currently in early development. Some features may be incomplete and/or not functioning.

UNITYREF

Your Pit Stop For Solving ANYTHING in Unity

assets

[Addressables] Fix Accentuated Filename Loading Failures in Builds

Solution

addressablesandroidmobile development

Unity 2021.3.x - Unity 6.3.x

Published 28 days ago

Issue

 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.

Explanation

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:

  1. Select the AddressableAssetSettings asset in your project.
  2. In the Inspector, locate the Internal Id Mode property.
  3. Change the value from Full Path to GUID.
  4. Open the Addressables Groups window.
  5. Select Build > New Build > Default Build Script to 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 Catalog checkbox is enabled if you are using manual GUID referencing.
  • Clear your Addressables build 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.