Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Cache::tags() throws because the cache driver in use has no tag support

ErrorBadMethodCallException: This cache store does not support tagging.

Short answer

Tags only work on cache stores that implement them. The file, dynamodb and database drivers do not, and a new Laravel app uses the database driver by default, so Cache::tags() throws. Point CACHE_STORE at a store that supports tags such as Redis, clear the cached config, or stop using tags and forget keys by name.

  • Applies to Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the cache settings the application really uses, not the ones in your .env file. Look at the default store and at the driver of that store.

    php artisan config:show cache
  2. 2Match what you see, then jump to its fix

    1. 1config:show shows a default of database or file, and the error comes from Cache::tags()The default store is file, database or dynamodbFix
    2. 2CACHE_STORE=redis in .env, and config:show still prints databaseThe .env file says Redis, but a cached config still holds the old storeFix
    3. 3The default store is fine, but the failing line is Cache::store('file')->tags(...) or another named storeThe code picks a store without tags for this callFix
    4. 4The store comes from Cache::extend() or a package, and the exception appears only with itA custom cache driver does not provide tagsFix

What does the error look like?

  • BadMethodCallException: This cache store does not support tagging.
  • This cache store does not support tagging.

Cause 1 of 4

The default store is file, database or dynamodb

1Check

The Laravel documentation says cache tags are not supported with the file, dynamodb and database drivers. A new application is configured to use the database driver by default. In the framework, Cache::tags() throws unless the store has a tags method, and the Redis store has one while the database store does not.

grep -n "CACHE_STORE" .env
php artisan config:show cache

2Fix

Switch the default store to Redis, which needs the PhpRedis extension or the predis/predis package. If you cannot change the store, remove the tags and forget the keys by name, then clear the cached config.

# .env
CACHE_STORE=redis

# without tags: one key per item, removed by name
Cache::put('posts:index', $posts, 600);
Cache::forget('posts:index');

3Verify

A tagged put and get works.

php artisan config:clear
# in php artisan tinker
>>> Cache::tags(['people'])->put('John', 'x', 60);
>>> Cache::tags(['people'])->get('John');

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

The .env file says Redis, but a cached config still holds the old store

1Check

After config:cache, the framework reads the cached file and the .env file is not loaded during requests. A change to .env has no effect until the cache is rebuilt.

php artisan config:show cache

2Fix

Clear the cached configuration, and rebuild it at deployment.

php artisan config:clear
# on production, after the .env change
php artisan config:cache

3Verify

config:show prints the store you set, and tags work.

php artisan config:show cache

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

The code picks a store without tags for this call

1Check

A call can choose a store by name. The tags() call then runs against that store, whatever the default is.

grep -rn "Cache::store(" app/

2Fix

Use a store with tag support for the tagged calls, such as redis.

Cache::store('redis')->tags(['people', 'artists'])->put('John', $john, $seconds);

3Verify

The tagged call runs without the exception.

# in php artisan tinker
>>> Cache::store('redis')->tags(['people'])->put('John', 'x', 60);

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

A custom cache driver does not provide tags

1Check

In the framework, tags() works only when the store has a tags method. The built-in Redis store inherits it from the TaggableStore base class, and the database store does not.

grep -rn "Cache::extend(" app/

2Fix

Make the custom store extend Illuminate\Cache\TaggableStore, or leave tags out for that store.

use Illuminate\Cache\TaggableStore;

class MongoStore extends TaggableStore
{
    // get, put, forget, flush ... as before
}

3Verify

Cache::tags() on that store returns a tagged cache and no exception.

# in php artisan tinker
>>> Cache::store('mongo')->tags(['people']);

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Pick the cache driver for what the application needs: if you use tags, use a store that has them in every environment, including local and CI.
  • Set CACHE_STORE explicitly in .env and in the deployment settings, not only through the default.
  • Run php artisan config:clear after an environment change, and config:cache only in the deployment step.
  • Keep tag names in one class or enum, so the code that tags and the code that flushes agree.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.