apache/cassandra · error · InvalidRequestException

Got null for INSERT JSON values

Error message

Got null for INSERT JSON values

What it means

Json.parseJson throws this InvalidRequestException when the JSON string supplied to INSERT JSON (or ... AS JSON paths) deserializes to a JSON null instead of an object. Cassandra requires a JSON object mapping column names to values; a literal 'null' document carries no column data.

Source

Thrown at src/java/org/apache/cassandra/cql3/Json.java:278

        }

        @Override
        public void addFunctionsTo(List<Function> functions)
        {
        }
    }

    /**
     * Given a JSON string, return a map of columns to their values for the insert.
     */
    static Map<ColumnIdentifier, Term> parseJson(String jsonString, Collection<ColumnMetadata> expectedReceivers)
    {
        try
        {
            Map<String, Object> valueMap = JsonUtils.JSON_OBJECT_MAPPER.readValue(jsonString, Map.class);

            if (valueMap == null)
                throw new InvalidRequestException("Got null for INSERT JSON values");

            JsonUtils.handleCaseSensitivity(valueMap);

            Map<ColumnIdentifier, Term> columnMap = new HashMap<>(expectedReceivers.size());
            for (ColumnSpecification spec : expectedReceivers)
            {
                // We explicitely test containsKey() because the value itself can be null, and we want to distinguish an
                // explicit null value from no value
                if (!valueMap.containsKey(spec.name.toString()))
                    continue;

                Object parsedJsonObject = valueMap.remove(spec.name.toString());
                if (parsedJsonObject == null)
                {
                    // This is an explicit user null
                    columnMap.put(spec.name, Constants.NULL_VALUE);
                }
                else

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the JSON argument is an object like '{"col": "value"}', never 'null'
2. Check the application variable feeding the JSON string for null/"null" values before executing
3. Guard at the API layer: reject empty or null JSON bodies before issuing INSERT JSON
4. Use fromJsonObject/toJson round-trips in tests to validate the payload

Example fix

// before
String json = null; // or "null"
session.execute("INSERT INTO t JSON ?", json);
// after
if (json == null || json.equals("null")) throw new IllegalArgumentException("JSON payload required");
session.execute("INSERT INTO t JSON ?", json);

void requireJsonObject(String json) {
    if (json == null || json.trim().isEmpty() || "null".equals(json.trim()))
        throw new IllegalArgumentException("INSERT JSON payload must be a JSON object, got: " + json);
    if (json.trim().charAt(0) != '{')
        throw new IllegalArgumentException("INSERT JSON payload must start with '{'");
}

try { session.execute("INSERT INTO t JSON ?", json); } catch (InvalidRequestException e) { if (e.getMessage().contains("Got null")) throw new IllegalArgumentException("Null JSON payload", e); throw e; }

When it happens

Trigger: Executing INSERT INTO t JSON 'null' or binding a prepared-statement JSON string whose parsed Map is null (e.g. the string "null" was passed as jsonString).

Common situations: Application code passing an uninitialized/serialized-null value into a JSON INSERT; API payloads where the body was 'null' and forwarded verbatim; template-generated queries with a missing object.

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

• Error decoding JSON value for %s: %s
• JSON values map contains unrecognized column: %s
• Could not decode JSON string as a map: %s. (String was: %s)
• (dynamic MarshalException message)
• Got null for INSERT JSON values

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/2887b2787f692777. Report an issue: GitHub.