Troubleshooting

Unknown command FT.CREATE

The connected Redis server does not have the RediSearch module. Use Redis Stack or install RediSearch on the server. Confirm the module with:

redis-cli MODULE LIST

Look for the search module.

No schema is configured

The key in schemas must exactly match the model’s searchableAs() result or the name passed to within():

public function searchableAs(): string
{
    return 'users';
}

The matching configuration key is schemas.users.

A filter returns no records

Confirm that exact-value fields are TAG, ranges are NUMERIC, and the same field is returned by toSearchableArray(). Recreate and re-import the index after changing its schema.

Sorting fails

Add sortable => true to the field, recreate the index, and import the models again:

'created_at' => [
    'type' => 'NUMERIC',
    'sortable' => true,
],

Search results lag behind writes

When Scout queueing is enabled, the queue worker must process the indexing job before the record becomes searchable:

php artisan queue:work

For a synchronous local check, call searchable() explicitly after creating the model or temporarily disable Scout queueing in the test environment.

Prefix search does not match a short term

The default minimum prefix length is two characters. Change it globally or per query:

SCOUT_REDIS_SEARCH_PREFIX_MIN_LENGTH=1

User::search('A')->options(['prefix_min_length' => 1])->get();

Existing documents use an old schema

Deleting and recreating an index does not repopulate it. Run an import after the new index is created:

php artisan scout:delete-index users
php artisan scout:index users
php artisan scout:import "App\Models\User"