Dealing with “Invalid usage of the option ONLINE in the CREATE JSON INDEX statement” in SQL Server

by

If you’re trying to set the ONLINE option when creating a JSON index in SQL Server, but you’re seeing “Invalid usage of the option ONLINE in the CREATE JSON INDEX statement“, don’t worry – it might not be an error on your part.

It probably depends on things like, are you trying to set ONLINE = ON or ONLINE = OFF? And are you trying to do it around the time I write this article, or sometime in the future?

Let’s take a quick look at what could be happening when you try to use this option.

Example of Error

Here’s an example of code that produces the error:

CREATE JSON INDEX ix_tickets_details
    ON support_tickets (details)
    WITH (ONLINE = ON);

Output:


Msg 153, Level 15, State 35, Line 3
Invalid usage of the option ONLINE in the CREATE JSON INDEX statement.

We get an error. This is to be expected (at least, in SQL Server 2025), as the Microsoft docs explicitly state that ONLINE = ON will lead to an error:

In this version of SQL Server, online index builds aren’t supported for JSON indexes. If this option is set to ON for a JSON index, an error is raised. Either omit the ONLINE option or set ONLINE to OFF.

The docs imply that we can use ONLINE = OFF without error, and that only ONLINE = ON causes an error.

But that seems to conflict with my own observations. Here’s what happens when I use ONLINE = OFF:

CREATE JSON INDEX ix_tickets_details
    ON support_tickets (details)
    WITH (ONLINE = OFF);

Output:


Msg 153, Level 15, State 35, Line 3
Invalid usage of the option ONLINE in the CREATE JSON INDEX statement.

Exactly the same error. Seems we can’t use the ONLINE option, even if it’s to set it to OFF. At least, this is the case in the SQL Server version/edition that I used to run that code, which is SQL Server 2025 Enterprise Developer Edition (64-bit) on Linux (Ubuntu 24.04.3 LTS) <X64>.

Solution

The solution is easy, simply omit the ONLINE option from the statement altogether:

CREATE JSON INDEX ix_tickets_details
    ON support_tickets (details);

Result:

Commands completed successfully.

This time it worked.

This is the same outcome that we’d have seen with ONLINE = OFF anyway. Given SQL Server doesn’t (currently) support ONLINE = ON, the only option we have is to leave it OFF. So we’re not losing any functionality with this solution.

By the way, the Microsoft docs use the phrase “In this version of SQL Server”, which relates to SQL Server 2025 (17.x) at the time of this article. Things may change in future versions, so bear that in mind when reading this article.