laravel/framework · error · InvalidArgumentException

Index name contains invalid characters.

Error message

Index name contains invalid characters.

What it means

SqlServerGrammar::compileIndexHint() throws InvalidArgumentException when a force-type hint's index name fails the regex /^[a-zA-Z0-9_$]+$/. SQL Server compiles forceIndex to WITH (INDEX([...])) and only supports the force type; use/ignore hints return empty string and are not validated.

Source

Thrown at src/Illuminate/Database/Query/Grammars/SqlServerGrammar.php:126

    /**
     * Compile the index hints for the query.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  \Illuminate\Database\Query\IndexHint  $indexHint
     * @return string
     *
     * @throws \InvalidArgumentException
     */
    protected function compileIndexHint(Builder $query, $indexHint)
    {
        if ($indexHint->type !== 'force') {
            return '';
        }

        $index = $indexHint->index;

        if (! preg_match('/^[a-zA-Z0-9_$]+$/', $index)) {
            throw new InvalidArgumentException('Index name contains invalid characters.');
        }

        return "with (index([{$index}]))";
    }

    /**
     * {@inheritdoc}
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $where
     * @return string
     */
    protected function whereBitwise(Builder $query, $where)
    {
        $value = $this->parameter($where['value']);

        $operator = str_replace('?', '??', $where['operator']);

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Pass the bare SQL Server index name containing only [a-zA-Z0-9_$].
2. Guard forceIndex behind a driver check and skip it for SQL Server if not essential.
3. Rename the index to use underscore-safe characters.

Example fix

// before
$query->from('users')->forceIndex('idx.active.users');

// after
$query->from('users')->forceIndex('idx_active_users');

// SQL Server only validates force-type hints
if ($query->getConnection()->getDriverName() === 'sqlsrv' && $hintType === 'force') {
    if (! preg_match('/^[a-zA-Z0-9_$]+$/', $index)) {
        throw new \InvalidArgumentException("Invalid SQL Server index name: {$index}");
    }
}
$query->from('users')->forceIndex($index);

function isValidSqlServerIndexName(string $name): bool
{
    return (bool) preg_match('/^[a-zA-Z0-9_$]+$/', $name);
}

When it happens

Trigger: Calling forceIndex($name) on a sqlsrv connection where $name contains characters outside [a-zA-Z0-9_$] (hyphen, space, dot, brackets). useIndex/ignoreIndex do not throw on SQL Server.

Common situations: Porting MySQL index-hint code to SQL Server where the index name has a different format. Using bracketed/qualified index identifiers that contain invalid characters.

Related errors

• Index name contains invalid characters.
• Index name contains invalid characters.
• The given password does not match the current password.
• You requested {$requested} items, but there are only {$count
• $count items were found.

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/766d95b207a3032d.json. Report an issue: GitHub.