EllanJiang/GameFramework · error · GameFrameworkException

String ' ' is too long.

Error message

String '{0}' is too long.

What it means

FileSystem.StringData.SetString converts a string to bytes and stores its length in a single byte, so strings longer than 255 bytes cannot be stored. GameFramework detects this and throws instead of silently truncating.

Solutions

1. Validate that Utility.Converter.GetBytes(value) returns at most 255 bytes before calling SetString
2. Shorten or truncate the string by encoded byte count, not character count, accounting for multibyte characters
3. Store long strings in a separate file outside the filesystem metadata instead of in StringData
4. Use ASCII-safe names where possible to maximize the usable length

Example fix

// before
stringData.SetString(longName); // may exceed 255 encoded bytes
// after
int byteLen = Utility.Converter.GetBytes(longName, s_CachedBytes);
if (byteLen > byte.MaxValue) longName = TruncateToBytes(longName, byte.MaxValue);
stringData.SetString(longName);

int len = Utility.Converter.GetBytes(value, s_CachedBytes);
if (len > byte.MaxValue) throw new ArgumentException($"String exceeds {byte.MaxValue} encoded bytes", nameof(value));
stringData.SetString(value);

bool FitsStringData(string s) { var b = new List<byte>(); Utility.Converter.GetBytes(s, b); return b.Count <= byte.MaxValue; }

try { stringData.SetString(value); }
catch (GameFrameworkException ex) when (ex.Message.Contains("is too long")) { value = TruncateToBytes(value, byte.MaxValue); stringData.SetString(value); }

When it happens

Trigger: Calling SetString with a string whose UTF-8/encoded byte count (from Utility.Converter.GetBytes) exceeds 255 while the filesystem is in write mode. Note the limit is on encoded BYTES, not characters — multibyte characters hit it sooner.

Common situations: Storing file names or metadata with long non-ASCII text (e.g. CJK or emoji names) where 255 characters fit but 255 bytes do not; user-generated names without length validation in editor tooling.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• Offset is invalid.
• Length is invalid.
• Full path is invalid.
• Access is invalid.
• Stream is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/4c33f6c949a167ea. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/FileSystem/FileSystem.StringData.cs:56

                    return null;
                }

                Array.Copy(m_Bytes, 0, s_CachedBytes, 0, m_Length);
                Utility.Encryption.GetSelfXorBytes(s_CachedBytes, 0, m_Length, encryptBytes);
                return Utility.Converter.GetString(s_CachedBytes, 0, m_Length);
            }

            public StringData SetString(string value, byte[] encryptBytes)
            {
                if (string.IsNullOrEmpty(value))
                {
                    return Clear();
                }

                int length = Utility.Converter.GetBytes(value, s_CachedBytes);
                if (length > byte.MaxValue)
                {
                    throw new GameFrameworkException(Utility.Text.Format("String '{0}' is too long.", value));
                }

                Utility.Encryption.GetSelfXorBytes(s_CachedBytes, encryptBytes);
                Array.Copy(s_CachedBytes, 0, m_Bytes, 0, length);
                return new StringData((byte)length, m_Bytes);
            }

            public StringData Clear()
            {
                return new StringData(0, m_Bytes);
            }
        }
    }
}

View on GitHub (pinned to d0c010b051)