EllanJiang/GameFramework · error · GameFrameworkException

JSON helper is invalid.

Error message

JSON helper is invalid.

What it means

Utility.Json.ToJson(object) throws GameFrameworkException("JSON helper is invalid.") when the static s_JsonHelper has not been set. GameFramework's JSON utility is decoupled from any specific JSON library: you must register an IJsonHelper implementation (e.g. via Utility.Json.SetJsonHelper) before using ToJson/ToObject. Without registration the utility has nothing to delegate to and fails fast.

Solutions

1. Register a JSON helper at startup before any serialization, e.g. via the framework's GameEntry or Utility.Json.SetJsonHelper(new NewtonsoftJsonHelper()).
2. Check initialization order: ensure the framework entry point runs before components that call ToJson.
3. Guard calls with a null/state check or move serialization to a later lifecycle phase.

Example fix

// before
string json = Utility.Json.ToJson(saveData); // throws: helper not set
// after
void Awake()
{
    Utility.Json.SetJsonHelper(new NewtonsoftJsonHelper()); // register first
}
string json = Utility.Json.ToJson(saveData);

// run once during startup, before any serialization
if (Utility.Json.ToJsonable == null) { /* or check via try/catch below */ }
GameEntry.GetComponent<JsonObjectHelper>(); // or:
Utility.Json.SetJsonHelper(new Utility.JsonHelper()); // register concrete IJsonHelper first

bool JsonReady { get { try { Utility.Json.ToJson(new object()); return true; } catch (GameFrameworkException) { return false; } } }

try { return Utility.Json.ToJson(obj); }
catch (GameFrameworkException ex) when (ex.Message == "JSON helper is invalid.")
{
    Log.Error("JSON helper not registered — call SetJsonHelper during startup");
    throw; // or fall back to manual serialization
}

When it happens

Trigger: Calling Utility.Json.ToJson(obj) (or ToObject) before SetJsonHelper was called — typically during early startup, in editor scripts running before game initialization, or after forgetting to register the helper (e.g. missing the Newtonsoft.Json-based helper component in a Unity scene/GameEntry).

Common situations: New Unity projects where the GameFramework JSON helper (like the litjson or Newtonsoft adapter) was not added; initialization order issues where a service serializes before the framework's GameEntry.Awake runs; stripping/IL2CPP removing the helper assembly.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• You must set resource manager first.
• You must set data provider helper first.
• You must set data helper first.
• Resource manager is invalid.
• Data provider helper is invalid.

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

Appendix: source

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

            /// <summary>
            /// 设置 JSON 辅助器。
            /// </summary>
            /// <param name="jsonHelper">要设置的 JSON 辅助器。</param>
            public static void SetJsonHelper(IJsonHelper jsonHelper)
            {
                s_JsonHelper = jsonHelper;
            }

            /// <summary>
            /// 将对象序列化为 JSON 字符串。
            /// </summary>
            /// <param name="obj">要序列化的对象。</param>
            /// <returns>序列化后的 JSON 字符串。</returns>
            public static string ToJson(object obj)
            {
                if (s_JsonHelper == null)
                {
                    throw new GameFrameworkException("JSON helper is invalid.");
                }

                try
                {
                    return s_JsonHelper.ToJson(obj);
                }
                catch (Exception exception)
                {
                    if (exception is GameFrameworkException)
                    {
                        throw;
                    }

                    throw new GameFrameworkException(Text.Format("Can not convert to JSON with exception '{0}'.", exception), exception);
                }
            }

            /// <summary>

View on GitHub (pinned to d0c010b051)