EllanJiang/GameFramework · error · GameFrameworkException

Format is invalid.

Error message

Format is invalid.

What it means

Utility.Text.Format<T>(string format, T arg) throws when the format string is null. The method routes to a configured TextHelper or falls back to string.Format, both of which require a non-null format string. The library fails fast with GameFrameworkException rather than returning null.

Solutions

1. Ensure the format string is non-null; check the source (localization/config lookup) for missing keys.
2. Provide a default format string when the lookup fails.
3. Validate format strings at load time so missing keys are caught at startup.

Example fix

// before
string fmt = localization.GetString(key); // may be null
string text = Utility.Text.Format(fmt, value);
// after
string fmt = localization.GetString(key) ?? "Value: {0}";
string text = Utility.Text.Format(fmt, value);

if (format == null)
    format = DefaultFormat;
string text = Utility.Text.Format(format, arg);

bool HasFormat(string format) => format != null;

try
{
    string text = Utility.Text.Format(fmt, arg);
}
catch (GameFrameworkException ex) when (ex.Message == "Format is invalid.")
{
    // missing localization key: fall back to a default string
}

When it happens

Trigger: Calling Utility.Text.Format<string>(null, arg) — typically because the format string came from a localization table, config value, or resource key lookup that returned null.

Common situations: Missing localization key so the lookup returns null; a config field left blank; refactoring where a format constant was deleted but a call site remained.

Related errors

• Entity asset name is invalid.
• Buffer is invalid.
• Resource manager is invalid.
• Data provider helper is invalid.
• appendErrorMessage

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

Appendix: source

Thrown at GameFramework/Utility/Utility.Text.cs:39

            /// </summary>
            /// <param name="textHelper">要设置的字符辅助器。</param>
            public static void SetTextHelper(ITextHelper textHelper)
            {
                s_TextHelper = textHelper;
            }

            /// <summary>
            /// 获取格式化字符串。
            /// </summary>
            /// <typeparam name="T">字符串参数的类型。</typeparam>
            /// <param name="format">字符串格式。</param>
            /// <param name="arg">字符串参数。</param>
            /// <returns>格式化后的字符串。</returns>
            public static string Format<T>(string format, T arg)
            {
                if (format == null)
                {
                    throw new GameFrameworkException("Format is invalid.");
                }

                if (s_TextHelper == null)
                {
                    return string.Format(format, arg);
                }

                return s_TextHelper.Format(format, arg);
            }

            /// <summary>
            /// 获取格式化字符串。
            /// </summary>
            /// <typeparam name="T1">字符串参数 1 的类型。</typeparam>
            /// <typeparam name="T2">字符串参数 2 的类型。</typeparam>
            /// <param name="format">字符串格式。</param>
            /// <param name="arg1">字符串参数 1。</param>
            /// <param name="arg2">字符串参数 2。</param>

View on GitHub (pinned to d0c010b051)