What causes "Got null for INSERT JSON values" in apache/cassandra?

Bind a valid JSON string (non-null) to the INSERT JSON parameter before executing.

apache/cassandra · error · InvalidRequestException

Got null for INSERT JSON values

Error message

Got null for INSERT JSON values

What it means

QueryOptions.getJsonColumnValue() reads the bound value for an INSERT JSON statement. A null ByteBuffer at the bind index means no value was supplied for the JSON payload, so Json.parseJson would have nothing to parse; the driver/client sent an unset or null bind marker for the JSON value.

Source

Thrown at src/java/org/apache/cassandra/cql3/QueryOptions.java:201

     * @param columnName the name of the column we want the value of.
     * @param expectedReceivers the columns expected in the JSON value at index {@code bindIndex}. This is only used when parsing the
     * json initially and no check is done afterwards. So in practice, any call of this method on the same QueryOptions object and with the same
     * {@code bindIndx} values should use the same value for this parameter, but this isn't validated in any way.
     *
     * @return the value correspong to column {@code columnName} in the (JSON) bind value at index {@code bindIndex}. This may return null if the
     * JSON value has no value for this column.
     */
    public Term getJsonColumnValue(int bindIndex, ColumnIdentifier columnName, Collection<ColumnMetadata> expectedReceivers) throws InvalidRequestException
    {
        if (jsonValuesCache == null)
            jsonValuesCache = new ArrayList<>(Collections.<Map<ColumnIdentifier, Term>>nCopies(getValues().size(), null));

        Map<ColumnIdentifier, Term> jsonValue = jsonValuesCache.get(bindIndex);
        if (jsonValue == null)
        {
            ByteBuffer value = getValues().get(bindIndex);
            if (value == null)
                throw new InvalidRequestException("Got null for INSERT JSON values");

            jsonValue = Json.parseJson(UTF8Type.instance.getSerializer().deserialize(value), expectedReceivers);
            jsonValuesCache.set(bindIndex, jsonValue);
        }

        return jsonValue.get(columnName);
    }

    /**
     * Tells whether or not this <code>QueryOptions</code> contains the column specifications for the bound variables.
     * <p>The column specifications will be present only for prepared statements.</p>
     * @return <code>true</code> this <code>QueryOptions</code> contains the column specifications for the bound
     * variables, <code>false</code> otherwise.
     */
    public boolean hasColumnSpecifications()
    {
        return false;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Bind a valid JSON string (non-null) to the INSERT JSON parameter before executing.
Verify the number of positional values matches the number of bind markers in the statement.
Check the driver version for known bugs around JSON bind values and unset values.

Example fix

// before
session.execute(stmt.bind(null));
// after
String json = "{\"id\":1,\"name\":\"a\"}";
session.execute(stmt.bind(json));

Defensive patterns

Strategy: type-guard

Validate before calling

if (jsonString == null || jsonString.isEmpty()) throw new IllegalArgumentException("INSERT JSON requires a non-null JSON string");

Type guard

if (!(json instanceof String) || ((String) json).isEmpty()) throw new IllegalArgumentException("JSON payload must be a non-empty string");

Try / catch

try { session.execute(jsonInsert.bind(json)); } catch (InvalidRequestException e) { if (e.getMessage().contains("Got null for INSERT JSON values")) { /* fix binding */ } }

Prevention

Always bind a real value to JSON insert markers
Assert value count equals marker count before execute
Avoid null JSON strings in data pipelines

When it happens

Trigger: INSERT INTO ... JSON ? with the JSON string bind parameter bound to null or left unset (UNSET_BYTE_BUFFER pathway), or a driver sending an insufficient number of values so getValues().get(bindIndex) is null.

Common situations: Driver bug or misuse of the raw protocol binding fewer values than markers; application code passing a null JSON string; serializing batch statements where one JSON insert lacks its bound value.

Related errors

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