{"record":{"id":"6e92b02d90d3b9f8","repo":"tui-cs/Terminal.Gui","slug":"configuration-json-root-must-not-be-null","errorCode":null,"errorMessage":"Configuration JSON root must not be null.","messagePattern":"Configuration JSON root must not be null\\.","errorType":"exception","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Configuration/SourcesManager.cs","lineNumber":163,"sourceCode":"    {\n        if (settingsScope is null)\n        {\n            return false;\n        }\n\n        // Update the existing settings with the new settings.\n        try\n        {\n#if DEBUG\n            string? json = new StreamReader (stream).ReadToEnd ();\n            stream.Position = 0;\n            Debug.Assert (json != null);\n#endif\n            SettingsScope? scope = JsonSerializer.Deserialize (stream, TuiSerializerContext.Instance.SettingsScope);\n\n            if (scope is null)\n            {\n                throw new JsonException (\"Configuration JSON root must not be null.\");\n            }\n\n            settingsScope.UpdateFrom (scope);\n            ConfigurationManager.OnUpdated ();\n\n            AddSource (location, source);\n\n            Logging.Trace ($\"Read configuration from \\\"{source}\\\" - ConfigLocation: {location}\");\n\n            Trace.Configuration (source, \"Load\", $\"location={location}\");\n\n            return true;\n        }\n        catch (JsonException e)\n        {\n            if (ConfigurationManager.ThrowOnJsonErrors ?? false)\n            {\n                throw;","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Configuration/SourcesManager.cs#L145-L181","documentation":"Thrown by SourcesManager.Load(Stream,...) when JsonSerializer.Deserialize returns null for the SettingsScope root — meaning the JSON document's root token was the literal 'null'. Terminal.Gui requires a JSON object as the configuration root. Note: this JsonException is caught immediately after (SourcesManager.cs:177) and only re-thrown if ConfigurationManager.ThrowOnJsonErrors is true (default false); otherwise it is recorded via ConfigurationManager.AddJsonError and printed at Application shutdown.","triggerScenarios":"A config file (.tui/config.json, <App>.config.json, a TUI_CONFIG-pointed file, or an embedded resource) whose entire contents are the four bytes 'null'. Also possible if a custom RuntimeConfig string is set to \"null\".","commonSituations":"A tool or script wrote the literal string \"null\" into the config file; a previous failed write left a placeholder; a user typed 'null' thinking it clears settings.","solutions":["Replace the file contents with a valid JSON object (at minimum '{}') or delete the file so Terminal.Gui falls back to defaults.","Set ConfigurationManager.ThrowOnJsonErrors = false (the default) so a bad file is logged but does not crash startup, then fix the file.","If it comes from TUI_CONFIG, unset the env var or point it at a valid JSON object."],"exampleFix":"// before: .tui/config.json\nnull\n// after: .tui/config.json\n{\n  \"Theme\": \"Default\"\n}","handlingStrategy":"validation","validationCode":"// Reject a 'null' root before handing the stream to Terminal.Gui\nusing JsonDocument doc = JsonDocument.Parse (stream);\nstream.Position = 0;\nif (doc.RootElement.ValueKind == JsonValueKind.Null)\n    throw new InvalidOperationException (\"Config root is the literal null; replace with an object.\");","typeGuard":"static bool IsConfigRootValid (Stream s)\n{ s.Position = 0; try { using var d = JsonDocument.Parse (s); return d.RootElement.ValueKind == JsonValueKind.Object; } catch { return false; } finally { s.Position = 0; } }","tryCatchPattern":"ConfigurationManager.ThrowOnJsonErrors = false; // default; logs instead of throwing\ntry { /* load */ } catch (JsonException ex) when (ex.Message.Contains (\"must not be null\")) { /* handle */ }","preventionTips":["Treat config files as code: review them and lint them in CI.","Write config files atomically and never write the literal 'null'.","Set ThrowOnJsonErrors = false in production so a malformed file logs rather than crashes."],"tags":["config","json","sources-manager","config-root"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}