Handling System.Text.Json Deserialization Errors for Malformed JSON

Handling deserialization errors in System.Text.Json when dealing with malformed JSON requires implementing custom error handling strategies since the built-in JsonSerializer.Deserialize method throws exceptions on parsing errors. Unlike Newtonsoft.Json which offers an Error property in serializer options, System.Text.Json requires alternative approaches like custom converters, manual parsing with Utf8JsonReader, or using JsonDocument for partial deserialization to extract information from files with formatting issues such as unclosed curly braces and improperly escaped quotes.

Contents

• Understanding System.Text.Json Error Handling Limitations
• Custom JsonConverter for Tolerant Deserialization
• Using Utf8JsonReader for Manual Error Recovery
• JsonDocument for Partial Deserialization
• Configuring JsonSerializerOptions for Non-Standard JSON
• Schema Validation as an Alternative Approach
• Best Practices for Malformed JSON Handling

Understanding System.Text.Json Error Handling Limitations

System.Text.Json, introduced in .NET Core 3.0, provides high-performance JSON serialization and deserialization capabilities but lacks built-in error tolerance features that Newtonsoft.Json offers. When encountering malformed JSON with formatting errors like unclosed curly braces or improperly escaped quotes, the JsonSerializer.Deserialize method typically throws a JsonException that terminates the entire deserialization process.

The fundamental limitation lies in System.Text.Json’s design philosophy of strict JSON specification adherence. Unlike Newtonsoft.Json which allows configuring an Error event handler or property to continue processing after errors, System.Text.Json stops parsing at the first encountered error. This design choice prioritizes performance and correctness over flexibility for handling edge cases with malformed data.

According to community feedback on GitHub, developers have specifically requested similar error handling capabilities that Newtonsoft.Json provides. As noted in the .NET runtime issue tracker, there’s ongoing interest in adding error handling events to System.Text.Json that would allow developers to handle deserialization errors gracefully and continue processing when possible.

Understanding these limitations helps inform which alternative strategies might work best for your specific use case. For partially malformed JSON files, you’ll need to implement custom solutions that can either recover from specific error types or extract partial information despite the errors.

Custom JsonConverter for Tolerant Deserialization

A powerful approach to handling json parse error scenarios is implementing a custom JsonConverter that can gracefully handle exceptions during deserialization. Custom converters in System.Text.Json provide the flexibility to intercept the deserialization process and implement custom error recovery logic.

The first step is to create a converter that wraps the standard deserialization process within a try-catch block. When a JsonException occurs during deserialization, your converter can log the error and either return a default instance or attempt to recover based on the specific nature of the error.

Here’s a basic implementation pattern:

public class TolerantConverter<T> : JsonConverter<T> where T : new()
{
 public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
 {
 try
 {
 return JsonSerializer.Deserialize<T>(ref reader, options);
 }
 catch (JsonException ex)
 {
 // Log the error information
 Console.WriteLine($"Json parse error at position {reader.TokenStartPosition}: {ex.Message}");
 
 // Return a default instance or attempt partial recovery
 return new T();
 }
 }
 
 public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
 {
 JsonSerializer.Serialize(writer, value, options);
 }
}

For more sophisticated scenarios, you can enhance this converter to handle specific types of json parse error unexpected token situations. For example, you could implement logic to detect and handle common formatting issues:

1. Unclosed braces: Skip to the next complete object structure
2. Improperly escaped quotes: Attempt to normalize the quote escaping before deserialization
3. Trailing commas: Handle these by preprocessing the JSON string

To use this converter, register it with your JsonSerializerOptions:

var options = new JsonSerializerOptions
{
 Converters = { new TolerantConverter<MyClass>() }
};

A more advanced approach involves implementing stateful error recovery where your converter maintains context about what has been successfully parsed and attempts to continue from that point. This is particularly useful for json exception parse error scenarios where only part of the data is malformed.

The official Microsoft documentation on custom converters provides comprehensive guidance on implementing these patterns, including handling different JSON token types and implementing more complex error recovery logic. By leveraging these techniques, you can create robust deserialization that extracts meaningful information even from malformed JSON sources.

Using Utf8JsonReader for Manual Error Recovery

For fine-grained control over error handling, the Utf8JsonReader class provides a low-level streaming API that allows manual parsing of JSON content with custom error recovery logic. This approach gives you complete control over how to handle various json parse error scenarios.

The Utf8JsonReader reads JSON as a sequence of tokens without building an in-memory representation, making it particularly efficient for large or malformed JSON documents where you want to extract partial information. Here’s how to implement basic error recovery:

public static T ReadWithRecovery<T>(string json, JsonSerializerOptions options = null) 
 where T : new()
{
 var reader = new Utf8JsonReader(Encoding.UTF8.GetBytes(json));
 var result = new T();
 bool hasError = false;

 while (reader.Read())
 {
 try
 {
 switch (reader.TokenType)
 {
 case JsonTokenType.PropertyName:
 // Handle property names
 break;
 
 case JsonTokenType.StartObject:
 // Handle object start
 break;
 
 case JsonTokenType.EndObject:
 // Handle object end
 break;
 
 // Handle other token types...
 }
 }
 catch (JsonException ex)
 {
 Console.WriteLine($"Json parse error at position {reader.TokenStartPosition}: {ex.Message}");
 hasError = true;
 // Skip to the next complete token or implement custom recovery logic
 continue;
 }
 }

 return result;
}

This approach allows you to implement sophisticated error recovery strategies. For example, you could:

1. Skip malformed sections: When encountering an error, skip tokens until finding a known good structure
2. Attempt partial deserialization: Fill only the properties that can be successfully parsed
3. Normalize common issues: Fix simple formatting problems like improperly escaped quotes on-the-fly

A practical implementation might look like this for handling improperly escaped quotes:

private string NormalizeQuotes(string value)
{
 // Simple normalization of improperly escaped quotes
 return value.Replace(@"\""", "\"").Replace(@"\""", "\"");
}

The Utf8JsonReader approach is particularly effective when you need to handle json parse error unexpected token situations with specific recovery logic. By examining the reader’s current position and token type, you can implement context-aware error recovery that preserves as much data as possible.

Performance-wise, this streaming approach is more memory-efficient than loading entire JSON documents into memory, especially for large files. However, it requires more implementation effort compared to using JsonSerializer.Deserialize directly with a custom converter.

JsonDocument for Partial Deserialization

System.Text.Json.JsonDocument provides an alternative approach for handling malformed JSON by allowing you to parse the document and then selectively extract elements that are valid. This is particularly useful when dealing with json parse error scenarios where only portions of the document are malformed.

JsonDocument creates a read-only DOM (Document Object Model) representation of the JSON data that you can navigate. Unlike JsonSerializer.Deserialize, JsonDocument continues parsing after encountering errors, marking the problematic sections as invalid:

public static T PartialDeserialize<T>(string json) where T : new()
{
 var result = new T();
 var jsonBytes = Encoding.UTF8.GetBytes(json);
 
 using (var document = JsonDocument.Parse(json))
 {
 // Process the root element
 ProcessElement(document.RootElement, result);
 }
 
 return result;
}

private static void ProcessElement(JsonElement element, object target)
{
 // Handle different element types
 switch (element.ValueKind)
 {
 case JsonKind.Object:
 foreach (var property in element.EnumerateObject())
 {
 try
 {
 // Process each property
 ProcessProperty(property, target);
 }
 catch (JsonException ex)
 {
 Console.WriteLine($"Error processing property '{property.Name}': {ex.Message}");
 // Continue with next property
 }
 }
 break;
 
 case JsonKind.Array:
 foreach (var item in element.EnumerateArray())
 {
 try
 {
 ProcessElement(item, target);
 }
 catch (JsonException ex)
 {
 Console.WriteLine($"Error processing array item: {ex.Message}");
 // Continue with next item
 }
 }
 break;
 
 // Handle other value kinds...
 }
}

This approach has several advantages for handling json exception parse error situations:

1. Partial parsing: JsonDocument attempts to parse as much of the document as possible, even when errors occur
2. Error isolation: Problems in one section don’t prevent processing of other sections
3. Flexible navigation: You can selectively extract only the valid portions you need

However, JsonDocument also has limitations. It still throws exceptions for certain severe formatting issues, and the TryGet methods available on JsonElement have limitations in how gracefully they handle malformed content.

For more complex scenarios, you can implement a hybrid approach that combines JsonDocument with custom error handling logic. For example, you could preprocess the JSON to attempt to fix common issues before passing it to JsonDocument:

private static string PreprocessJson(string json)
{
 // Fix common issues like unclosed braces
 if (json.EndsWith("},") || json.EndsWith("],"))
 {
 json = json.Substring(0, json.Length - 1);
 }
 
 // Fix improperly escaped quotes (basic approach)
 json = json.Replace(@"\""", "\"");
 
 return json;
}

The JsonDocument approach is particularly valuable when you need to extract specific information from large, partially malformed JSON documents where implementing a full custom converter would be overly complex.

Configuring JsonSerializerOptions for Non-Standard JSON

System.Text.Json provides several configuration options in JsonSerializerOptions that can help handle non-standard or malformed JSON to some degree. While these don’t provide comprehensive error handling like Newtonsoft.Json’s Error property, they can mitigate certain types of json parse error scenarios.

The most relevant options for handling malformed JSON include:

var options = new JsonSerializerOptions
{
 AllowTrailingCommas = true,
 ReadCommentHandling = JsonCommentHandling.Skip,
 PropertyNameCaseInsensitive = true,
 NumberHandling = JsonNumberHandling.AllowReadingFromString
};

AllowTrailingCommas enables parsing of JSON that includes trailing commas after the last item in an object or array. This is one of the most common json parse error unexpected token scenarios, and this option can resolve many such issues without custom code.

ReadCommentHandling allows the parser to skip JSON comments (C-style /* */ and //), which aren’t part of the standard JSON specification but are commonly found in real-world JSON files. Setting this to JsonCommentHandling.Skip prevents parser errors when comments are present.

PropertyNameCaseInsensitive makes property name matching case-insensitive, which can help when dealing with inconsistent casing in JSON sources.

NumberHandling provides flexibility in how numbers are parsed, allowing strings that represent numbers to be converted properly.

For more complex json exception parse error scenarios, you might need to combine these options with custom preprocessing of the JSON string. Here’s an example of a preprocessing method that handles common issues:

private static string PrepareJsonForParsing(string json)
{
 if (string.IsNullOrEmpty(json))
 return json;

 // Remove BOM if present
 if (json[0] == '\ufeff')
 json = json.Substring(1);

 // Fix trailing commas
 json = Regex.Replace(json, @",(\s*[}]])", "$1");

 // Fix improperly escaped quotes (basic approach)
 json = json.Replace(@"\""", "\"");

 return json;
}

This preprocessing approach can handle many common json parse error scenarios before the JSON even reaches the parser. While not as sophisticated as Newtonsoft.Json’s Error property, this combination of configuration options and preprocessing can significantly improve your ability to handle malformed JSON with System.Text.Json.

For production scenarios, consider implementing more sophisticated preprocessing that can detect and handle a wider range of formatting issues. The key is to identify the specific types of malformed JSON you typically encounter and implement targeted fixes for those issues.

Schema Validation as an Alternative Approach

When dealing with consistently structured JSON that occasionally contains formatting errors, implementing schema validation before deserialization can provide an effective strategy for handling json parse error scenarios. This approach involves validating the JSON structure against an expected schema and attempting to correct or skip invalid portions.

The Json.Schema library (available as a NuGet package) provides comprehensive schema validation capabilities for .NET. Here’s how you can use schema validation to guide error recovery:

using Json.Schema;
using Json.Schema.DataGeneration;

public class SchemaValidatedDeserializer
{
 private readonly Schema _schema;
 
 public SchemaValidatedDeserializer(string schemaJson)
 {
 _schema = Schema.FromText(schemaJson);
 }
 
 public T Deserialize<T>(string json) where T : new()
 {
 // First validate against schema
 var validation = _schema.Validate(json);
 
 if (!validation.IsValid)
 {
 // Handle validation errors
 foreach (var error in validation.NestedErrors)
 {
 Console.WriteLine($"Schema validation error: {error.Message} at {error.SchemaLocation}");
 }
 
 // Attempt to fix common issues based on validation results
 json = FixBasedOnValidation(json, validation);
 }
 
 try
 {
 return JsonSerializer.Deserialize<T>(json);
 }
 catch (JsonException ex)
 {
 Console.WriteLine($"Json parse error: {ex.Message}");
 return new T(); // Return default or partially filled instance
 }
 }
 
 private string FixBasedOnValidation(string json, ValidationResults validation)
 {
 // Implement fixes based on validation errors
 // This is where you'd handle specific patterns of errors
 return json;
 }
}

Schema validation provides several advantages for handling malformed JSON:

1. Early detection: Identifies structural issues before attempting deserialization
2. Targeted fixes: You can implement specific fixes based on the types of validation errors encountered
3. Documentation: The schema serves as documentation for the expected JSON structure

For json parse error unexpected token scenarios, you can implement custom fix logic based on the validation results. For example, if validation indicates missing closing braces, you could add them:

private string FixMissingBraces(string json, ValidationResults validation)
{
 // Check for missing closing braces based on validation errors
 if (validation.NestedErrors.Any(e => e.Message.Contains("expected '}'")))
 {
 // Count opening and closing braces
 var openBraces = json.Count(c => c == '{');
 var closeBraces = json.Count(c => c == '}');
 
 // Add missing closing braces
 if (openBraces > closeBraces)
 {
 json += new string('}', openBraces - closeBraces);
 }
 }
 
 return json;
}

This approach is particularly effective when dealing with JSON that follows a consistent pattern but occasionally has specific types of formatting errors. By combining schema validation with targeted fixes, you can create a robust deserialization process that handles many common json exception parse error scenarios.

The schema validation approach works best when you have control over the JSON structure or when the malformed JSON follows predictable patterns. For completely unpredictable or severely malformed JSON, you might need to combine this approach with other strategies like Utf8JsonReader or custom converters.

Best Practices for Malformed JSON Handling

Implementing robust error handling for malformed JSON in System.Text.Json requires a combination of technical approaches and strategic considerations. Based on experience with various json parse error scenarios, here are best practices for dealing with malformed JSON data:

1. Implement Layered Error Handling

Rather than relying on a single approach, implement multiple layers of error handling:

• Preprocessing layer: Fix common issues before parsing
• Parser layer: Use tolerant deserialization strategies
• Application layer: Handle remaining gracefully

This layered approach ensures that issues are caught and handled at the most appropriate level, providing the best balance between robustness and performance.

2. Log Error Context Information

When encountering json parse error scenarios, log detailed context information to help diagnose and fix issues:

catch (JsonException ex)
{
 Console.WriteLine($"Json parse error at position {ex.LineNumber}:{ex.BytePositionInLine}");
 Console.WriteLine($"Error message: {ex.Message}");
 Console.WriteLine($"Partial data: {json.Substring(Math.Max(0, ex.BytePositionInLine - 50), 100)}");
}

This context information is invaluable for understanding the nature of malformed JSON and implementing targeted fixes.

3. Implement Gradual Degradation

Design your application to handle varying levels of JSON quality:

public T TryDeserialize<T>(string json) where T : new()
{
 // Try full deserialization first
 try
 {
 return JsonSerializer.Deserialize<T>(json);
 }
 catch (JsonException)
 {
 // If that fails, try with preprocessing
 try
 {
 var preprocessed = PreprocessJson(json);
 return JsonSerializer.Deserialize<T>(preprocessed);
 }
 catch (JsonException)
 {
 // If preprocessing fails, try partial deserialization
 return PartialDeserialize<T>(json);
 }
 }
}

This approach ensures that your application continues to function even with increasingly malformed JSON, providing value rather than failing completely.

4. Consider Performance Implications

Error handling strategies have different performance characteristics:

• Custom converters: Minimal overhead for valid JSON, significant overhead for malformed JSON
• Utf8JsonReader: More complex implementation but good performance for large files
• JsonDocument: Memory overhead but good for partial parsing

Choose the approach that best balances your performance requirements and the nature of your JSON data.

5. Validate Input When Possible

Implement input validation to catch common issues early:

private bool IsValidJsonStructure(string json)
{
 // Basic checks before attempting parsing
 if (string.IsNullOrWhiteSpace(json))
 return false;
 
 // Check for balanced braces and brackets
 var braces = json.Count(c => c == '{' || c == '}');
 if (braces % 2 != 0)
 return false;
 
 var brackets = json.Count(c => c == '[' || c == ']');
 if (brackets % 2 != 0)
 return false;
 
 return true;
}

6. Document Your Error Handling Strategy

Clearly document how your application handles malformed JSON, including:

• What types of errors are handled
• How the application behaves when errors occur
• Any preprocessing or normalization that occurs

This documentation helps other developers understand and maintain the error handling logic.

7. Test with Real-World Malformed JSON

Create comprehensive test cases with real-world examples of malformed JSON that your application might encounter. This includes:

• Files with unclosed braces
• Improperly escaped quotes
• Trailing commas
• Missing property values
• Invalid data types

Testing with realistic malformed JSON ensures that your error handling strategies work effectively in practice.

8. Monitor and Adapt

Monitor your application’s error handling in production and adapt your strategies based on the types of json parse error scenarios you encounter. This continuous improvement approach ensures that your error handling evolves to meet changing requirements.

By following these best practices, you can implement robust error handling for System.Text.Json that effectively deals with malformed JSON while maintaining good performance and user experience.

Sources

1. System.Text.Json GitHub Issue — Community request for error handling features similar to Newtonsoft.Json: https://github.com/dotnet/runtime/issues/51238
2. Makolyte Custom Converters Guide — Explanation of implementing custom converters for tolerant deserialization: https://makolyte.com/csharp-how-to-ignore-json-deserialization-errors/
3. Dev.to Non-Standard JSON Handling — Guide to configuring JsonSerializerOptions for non-standard JSON features: https://dev.to/prameshkc/handling-non-standard-json-in-net-using-systemtextjson-3e97
4. Endjin JsonElement Error Handling — Detailed explanation of JsonElement error handling behavior and limitations: https://endjin.com/blog/2024/02/dotnet-jsonelement-parse-errors
5. Microsoft Custom Converters Documentation — Official guidance on writing custom converters in System.Text.Json: https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/converters-how-to
6. Makolyte Converter Implementation — Examples of practical custom converter implementation for error handling: https://makolyte.com/system-text-json-how-to-customize-serialization-with-jsonconverter/

Conclusion

Handling deserialization errors in System.Text.Json for malformed JSON requires implementing custom strategies since the framework lacks built-in error tolerance features like Newtonsoft.Json’s Error property. By combining approaches such as custom JsonConverters for tolerant deserialization, Utf8JsonReader for manual error recovery, JsonDocument for partial parsing, and proper configuration of JsonSerializerOptions, you can effectively handle json parse error scenarios including unclosed braces and improperly escaped quotes. The most robust solutions implement layered error handling with preprocessing, validation, and graceful degradation, ensuring your application continues to function even with malformed JSON data. Remember to log detailed error context, test with real-world malformed examples, and continuously monitor and adapt your error handling strategies based on production experience.