OrchardCMS/OrchardCore · error · FormatException

Could not parse the JSON document.

Error message

Could not parse the JSON document.

What it means

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).

Solutions

  1. Open the InnerException and line/position info to find the exact malformed spot and fix the JSON syntax
  2. Validate the stream content with a JSON linter or JsonDocument.Parse in a check before feeding it to this parser
  3. Restore the configuration file from source control or a backup
  4. Check file encoding: re-save as UTF-8 without HTML/escape corruption

Example fix

// before
{"Logging": {"LogLevel": "Warning"},  // trailing comma not followed by property and missing closing brace
// after
{"Logging": {"LogLevel": "Warning"}}
Defensive patterns

Strategy: try-catch

Validate before calling

try { using var _ = JsonDocument.Parse(stream, JOptions.Document); stream.Position = 0; }
catch (JsonException jex) { throw new InvalidDataException($"Malformed JSON at offset {jex.BytePosition}", jex); }

Try / catch

try { JsonConfigurationParser.Parse(stream); }
catch (FormatException ex) when (ex.Message == "Could not parse the JSON document.")
{ log.LogError(ex.InnerException, "Invalid JSON at {Pos}", (ex.InnerException as JsonException)?.BytePosition); }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/4d0c0484c4e312b1. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Abstractions/Shell/Configuration/Internal/JsonConfigurationParser.cs:43

    private Dictionary<string, string?> ParseStream(Stream utf8Json)
    {
        try
        {
            using (var doc = JsonDocument.Parse(utf8Json, JOptions.Document))
            {
                if (doc.RootElement.ValueKind != JsonValueKind.Object)
                {
                    throw new FormatException($"Top-level JSON element must be an object. Instead, '{doc.RootElement.ValueKind}' was found.");
                }

                VisitObjectElement(doc.RootElement);
            }

            return _data;
        }
        catch (JsonException e)
        {
            throw new FormatException("Could not parse the JSON document.", e);
        }
    }

    private Dictionary<string, string?> ParseDocument(string document)
    {
        try
        {
            using (var doc = JsonDocument.Parse(document, JOptions.Document))
            {
                if (doc.RootElement.ValueKind != JsonValueKind.Object)
                {
                    throw new FormatException($"Top-level JSON element must be an object. Instead, '{doc.RootElement.ValueKind}' was found.");
                }

                VisitObjectElement(doc.RootElement);
            }

            return _data;

View on GitHub (pinned to 4306c0717f)