Jackson error "Illegal character... only regular white space allowed" when parsing JSON

3 min read 07-10-2024
Jackson error "Illegal character... only regular white space allowed" when parsing JSON


Decoding the Jackson "Illegal Character" JSON Parsing Error

Have you encountered the frustrating "Illegal character ((CTRL-CHAR),...) only regular white space allowed" error while parsing JSON with Jackson? This cryptic message can leave you scratching your head, wondering what went wrong.

Let's break down this common Jackson parsing error, understand its root cause, and explore solutions to get your JSON data flowing smoothly.

Understanding the Issue

Imagine you're trying to parse a JSON document with Jackson. You might expect a straightforward process, but sometimes things go wrong. The error message tells us that Jackson encountered a character it doesn't recognize within the JSON string. This character is likely a non-printable control character or a special character that's not allowed within JSON syntax.

The Code and the Scenario

Consider the following scenario:

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class JsonParsingError {

    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = "{ \"name\": \"John\", \"age\": 30, \"city\": \"New York\u000B\" }"; // Contains a vertical tab character
        JsonNode rootNode = mapper.readTree(jsonString);
        System.out.println(rootNode.path("city").asText());
    }
}

In this code, the jsonString contains a vertical tab character (\u000B) within the "city" field. This character is an invisible control character that is not allowed within JSON. When Jackson tries to parse this string, it encounters the control character and throws the "Illegal character" error.

Digging Deeper: The Root Cause

The root cause of this issue stems from the strict nature of JSON syntax. JSON specifies that the only allowed whitespace characters are space, tab, newline, and carriage return. Any other control characters or special characters not explicitly defined in the JSON standard are considered invalid.

Solutions: Identifying and Resolving the Error

  1. Check for Non-Printable Characters:

    The first step is to identify the culprit character. You can use a text editor with a feature to display non-printable characters or a tool like a hex editor to view the JSON string and pinpoint the problematic character.

  2. Remove or Escape Problematic Characters:

    Once you've found the culprit, you have two options:

    • Removal: Remove the invalid character from the JSON string. Be careful not to accidentally remove crucial data.
    • Escape: Escape the character using the backslash character (\) followed by the character's Unicode representation, e.g., \u000B.
  3. Utilize Jackson's JsonParser Customization:

    Jackson's JsonParser provides flexibility in handling special characters. You can use the JsonParser.Feature enum to configure your parser's behavior:

    import com.fasterxml.jackson.core.JsonParser;
    import com.fasterxml.jackson.databind.ObjectMapper;
    
    public class JsonParsingError {
    
        public static void main(String[] args) throws Exception {
            ObjectMapper mapper = new ObjectMapper();
            mapper.configure(JsonParser.Feature.ALLOW_UNQUOTED_CONTROL_CHARS, true); // Allows unquoted control characters
            String jsonString = "{ \"name\": \"John\", \"age\": 30, \"city\": \"New York\u000B\" }"; // Contains a vertical tab character
            JsonNode rootNode = mapper.readTree(jsonString);
            System.out.println(rootNode.path("city").asText());
        }
    }
    

    This approach allows Jackson to parse the JSON string with control characters, but it might lead to inconsistencies if the JSON data is not correctly formatted.

  4. Validate Your JSON Before Parsing:

    Before sending data to Jackson, consider using JSON schema validation to ensure the data adheres to the required format. This preventative measure can help catch errors before they reach your parser.

Wrapping Up

Encountering the Jackson "Illegal character" error can be frustrating, but understanding the root cause and the available solutions empowers you to troubleshoot effectively. Remember to carefully examine your JSON data for any invisible characters, and implement appropriate methods for removal, escaping, or parser customization to ensure successful JSON parsing.