What causes "PersistentLocalStorageSize must be between 256 and 4096, but was {0}" in Unity-Technologies/UnityCsReference?

Clamp the value to the valid range before assignment: value = Math.Max(256u, Math.Min(4095u, value))

Unity-Technologies/UnityCsReference · error · ArgumentException

PersistentLocalStorageSize must be between 256 and 4096, but

Error message

PersistentLocalStorageSize must be between 256 and 4096, but was {0}

What it means

PlayerSettings.XboxOne.PersistentLocalStorageSize is a uint property that reserves Persistent Local Storage (PLS) space in the Xbox One app manifest. The Xbox One platform requires the value to be between 256 and 4096 (MB). Setting a value outside this range throws ArgumentException with the attempted value. A value of 0 means no PLS reservation.

Source

Thrown at Editor/Mono/PlayerSettingsXboxOne.bindings.cs:288

            // *undocumented*
            [Obsolete("Starting May 11th 2020 any new base game submission releasing digital only, " +
                "digital and disc, or disc only, should not include a ratings element in the " +
                "AppxManifest. This ratings policy update applies to all Xbox supported ratings. " +
                "New base submissions that come in on or after this date will be " +
                "rejected by your Microsoft Representative if a ratings element is present.", false)]
            [NativeMethod("GetXboxOneGameRating")]
            [StaticAccessor("GetPlayerSettings().GetEditorOnly()", StaticAccessorType.Dot)]
            extern public static int GetGameRating(string name);

            // The presence of any other value than 0 for this property will result in a PLS reservation in your app manifest.
            public static uint PersistentLocalStorageSize
            {
                get { return persistentLocalStorageSizeInternal; }
                set
                {
                    if (value < 256 || value >= 4096)
                        throw new ArgumentException(string.Format("PersistentLocalStorageSize must be between 256 and 4096, but was {0}", value));

                    persistentLocalStorageSizeInternal = value;
                }
            }

            [NativeProperty("XboxOnePersistentLocalStorageSize", TargetType.Field)]
            extern private static uint persistentLocalStorageSizeInternal
            {
                [StaticAccessor("GetPlayerSettings().GetEditorOnly()", StaticAccessorType.Dot)]
                get;
                [StaticAccessor("GetPlayerSettings().GetEditorOnlyForUpdate()", StaticAccessorType.Dot)]
                set;
            }

            // Enable/Disable Type Optimization in C++ Compiler 'Master' build, applies to LTCG.
            [NativeProperty("XboxOneEnableTypeOptimization")]
            [StaticAccessor("GetPlayerSettings()", StaticAccessorType.Dot)]
            extern public static bool EnableTypeOptimization { get; set; }

View on GitHub (pinned to 225b0fbdb5)

Solutions

Clamp the value to the valid range before assignment: value = Math.Max(256u, Math.Min(4095u, value))
If no PLS reservation is needed, set the value to 0 (which is allowed and means no reservation)
Validate config file values against the 256-4095 range during project load
Use Math.Clamp(value, 256u, 4095u) (available in .NET Core 2.0+ / Unity 2019.4+)

Example fix

// before
PlayerSettings.XboxOne.PersistentLocalStorageSize = configuredPlsSize; // could be 100 or 5000

// after
uint plsSize = Math.Clamp(configuredPlsSize, 256u, 4095u);
if (configuredPlsSize == 0)
    plsSize = 0; // no reservation
PlayerSettings.XboxOne.PersistentLocalStorageSize = plsSize;

Defensive patterns

Strategy: validation

Validate before calling

uint plsSize = configuredValue;
if (plsSize != 0 && (plsSize < 256 || plsSize >= 4096))
    Debug.LogError($"PersistentLocalStorageSize {plsSize} is out of range [256, 4095] or 0 for none.");
else
    PlayerSettings.XboxOne.PersistentLocalStorageSize = plsSize;

Try / catch

try { PlayerSettings.XboxOne.PersistentLocalStorageSize = plsSize; }
catch (ArgumentException ex) when (ex.Message.Contains("PersistentLocalStorageSize"))
{ Debug.LogError($"Invalid PLS size. Must be 256-4095 or 0 for none. {ex.Message}"); }

Prevention

Clamp config-driven values with Math.Clamp(value, 256u, 4095u) before assignment
Document the valid range (256-4095 MB, or 0 for no reservation) in config file comments
Add a validation step in build scripts that checks PLS size before the build

When it happens

Trigger: Setting PlayerSettings.XboxOne.PersistentLocalStorageSize to a value less than 256 (e.g., 100) or greater than/equal to 4096 (e.g., 5000). Passing a value read from a config file or computed at runtime without range validation.

Common situations: Build scripts that read PLS size from a JSON/YAML config file and pass it directly without clamping. Porting a project from another platform where storage limits differ. Editor automation that sets PLS based on dynamic calculations.

Related errors

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/e52c71dcb0617d7f. Report an issue: GitHub.