{"record":{"id":"19db32dcb978c2c7","repo":"EllanJiang/GameFramework","slug":"json-helper-is-invalid","errorCode":null,"errorMessage":"JSON helper is invalid.","messagePattern":"JSON helper is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Utility/Utility.Json.cs","lineNumber":39,"sourceCode":"            /// <summary>\n            /// 设置 JSON 辅助器。\n            /// </summary>\n            /// <param name=\"jsonHelper\">要设置的 JSON 辅助器。</param>\n            public static void SetJsonHelper(IJsonHelper jsonHelper)\n            {\n                s_JsonHelper = jsonHelper;\n            }\n\n            /// <summary>\n            /// 将对象序列化为 JSON 字符串。\n            /// </summary>\n            /// <param name=\"obj\">要序列化的对象。</param>\n            /// <returns>序列化后的 JSON 字符串。</returns>\n            public static string ToJson(object obj)\n            {\n                if (s_JsonHelper == null)\n                {\n                    throw new GameFrameworkException(\"JSON helper is invalid.\");\n                }\n\n                try\n                {\n                    return s_JsonHelper.ToJson(obj);\n                }\n                catch (Exception exception)\n                {\n                    if (exception is GameFrameworkException)\n                    {\n                        throw;\n                    }\n\n                    throw new GameFrameworkException(Text.Format(\"Can not convert to JSON with exception '{0}'.\", exception), exception);\n                }\n            }\n\n            /// <summary>","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Utility/Utility.Json.cs#L21-L57","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Register a JSON helper at startup before any serialization, e.g. via the framework's GameEntry or Utility.Json.SetJsonHelper(new NewtonsoftJsonHelper()).","Check initialization order: ensure the framework entry point runs before components that call ToJson.","Guard calls with a null/state check or move serialization to a later lifecycle phase."],"exampleFix":"// before\nstring json = Utility.Json.ToJson(saveData); // throws: helper not set\n// after\nvoid Awake()\n{\n    Utility.Json.SetJsonHelper(new NewtonsoftJsonHelper()); // register first\n}\nstring json = Utility.Json.ToJson(saveData);","handlingStrategy":"validation","validationCode":"// run once during startup, before any serialization\nif (Utility.Json.ToJsonable == null) { /* or check via try/catch below */ }\nGameEntry.GetComponent<JsonObjectHelper>(); // or:\nUtility.Json.SetJsonHelper(new Utility.JsonHelper()); // register concrete IJsonHelper first","typeGuard":"bool JsonReady { get { try { Utility.Json.ToJson(new object()); return true; } catch (GameFrameworkException) { return false; } } }","tryCatchPattern":"try { return Utility.Json.ToJson(obj); }\ncatch (GameFrameworkException ex) when (ex.Message == \"JSON helper is invalid.\")\n{\n    Log.Error(\"JSON helper not registered — call SetJsonHelper during startup\");\n    throw; // or fall back to manual serialization\n}","preventionTips":["Register the IJsonHelper implementation in the earliest framework initialization (GameEntry/Awake).","Add a startup assertion that JSON serialization works before dependent systems initialize.","Keep the JSON helper assembly referenced and excluded from code stripping/IL2CPP managed stripping."],"tags":["json","initialization","missing-dependency","gameframework"],"backgroundTag":"missing-dependency","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}