{"record":{"id":"4d0c0484c4e312b1","repo":"OrchardCMS/OrchardCore","slug":"could-not-parse-the-json-document","errorCode":null,"errorMessage":"Could not parse the JSON document.","messagePattern":"Could not parse the JSON document\\.","errorType":"exception","errorClass":"FormatException","httpStatus":null,"severity":"error","filePath":"src/OrchardCore/OrchardCore.Abstractions/Shell/Configuration/Internal/JsonConfigurationParser.cs","lineNumber":43,"sourceCode":"    private Dictionary<string, string?> ParseStream(Stream utf8Json)\n    {\n        try\n        {\n            using (var doc = JsonDocument.Parse(utf8Json, JOptions.Document))\n            {\n                if (doc.RootElement.ValueKind != JsonValueKind.Object)\n                {\n                    throw new FormatException($\"Top-level JSON element must be an object. Instead, '{doc.RootElement.ValueKind}' was found.\");\n                }\n\n                VisitObjectElement(doc.RootElement);\n            }\n\n            return _data;\n        }\n        catch (JsonException e)\n        {\n            throw new FormatException(\"Could not parse the JSON document.\", e);\n        }\n    }\n\n    private Dictionary<string, string?> ParseDocument(string document)\n    {\n        try\n        {\n            using (var doc = JsonDocument.Parse(document, JOptions.Document))\n            {\n                if (doc.RootElement.ValueKind != JsonValueKind.Object)\n                {\n                    throw new FormatException($\"Top-level JSON element must be an object. Instead, '{doc.RootElement.ValueKind}' was found.\");\n                }\n\n                VisitObjectElement(doc.RootElement);\n            }\n\n            return _data;","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/OrchardCMS/OrchardCore/blob/4306c0717fe573f6fca1b4955909ddab6a192807/src/OrchardCore/OrchardCore.Abstractions/Shell/Configuration/Internal/JsonConfigurationParser.cs#L25-L61","documentation":"JsonConfigurationParser.ParseStream catches System.Text.Json.JsonException from JsonDocument.Parse and rethrows it as a FormatException with the message 'Could not parse the JSON document.', keeping the original exception as InnerException. It means the stream is not syntactically valid JSON at all (as opposed to being valid JSON with a wrong root kind).","triggerScenarios":"Calling JsonConfigurationParser.Parse(Stream) with a stream containing malformed JSON: trailing garbage, unquoted keys, unmatched braces, truncated file, or a non-UTF-8/HTML payload (e.g. an error page) rather than JSON.","commonSituations":"appsettings.json corrupted by a partial write or crash; a file saved with BOM/encoding issues after manual editing; pointing the parser at an HTML 404 page downloaded instead of a JSON config; copy/paste errors introducing stray commas or smart quotes.","solutions":["Open the InnerException and line/position info to find the exact malformed spot and fix the JSON syntax","Validate the stream content with a JSON linter or JsonDocument.Parse in a check before feeding it to this parser","Restore the configuration file from source control or a backup","Check file encoding: re-save as UTF-8 without HTML/escape corruption"],"exampleFix":"// before\n{\"Logging\": {\"LogLevel\": \"Warning\"},  // trailing comma not followed by property and missing closing brace\n// after\n{\"Logging\": {\"LogLevel\": \"Warning\"}}","handlingStrategy":"try-catch","validationCode":"try { using var _ = JsonDocument.Parse(stream, JOptions.Document); stream.Position = 0; }\ncatch (JsonException jex) { throw new InvalidDataException($\"Malformed JSON at offset {jex.BytePosition}\", jex); }","typeGuard":null,"tryCatchPattern":"try { JsonConfigurationParser.Parse(stream); }\ncatch (FormatException ex) when (ex.Message == \"Could not parse the JSON document.\")\n{ log.LogError(ex.InnerException, \"Invalid JSON at {Pos}\", (ex.InnerException as JsonException)?.BytePosition); }","preventionTips":["Run a JSON linter on config files in CI","Restore configs from source control rather than hand-editing in place","Watch for truncation on network/pipe sources","Use UTF-8 encoding for all config streams"],"tags":["json","configuration","parse"],"backgroundTag":"json-parse-error","analyzedSha":"4306c0717fe573f6fca1b4955909ddab6a192807","analyzedAt":"2026-09-13T17:41:05.024Z","contentChangedAt":"2026-09-13T17:41:05.024Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}