Understanding the Asset Container Contents cache in Statamic

In February 2025, Statamic 5.48.0 was released, and a PR from the insanely talented Ryan Mitchell introduced a new Asset Container Cache. Any guesses what it does? Yeah, it caches the contents of your Asset containers.

Yesterday at Mity Digital, while Michael was getting a site on to the staging environment, he noticed something: all of the assets were missing. We looked at the files on the server, and yep, there they were, and then it clicked… assets now get cached.

Caches are awesome as they can significantly improve performance – especially on large data sets, such as recursively browsing all of the assets within a container.

To be totally honest, I’m surprised it took 7 months to actually stumble up on this.

Basically here’s what happened. 

The site was deployed to the staging environment before a lot of the work was done: and the CP was accessed, and the Assets container was viewed.

This cached the contents of the Asset container.

Flash forward to all of the work being done, with dozens of new assets added, and the site was ready to be re-deployed.

The site was re-deployed, and all of those new assets were pulled from the repository and now exist on the server’s file system.

The catch: this has nothing to do with Statamic, and because the Assets container has its contents cached (and cached forever), it has no knowledge of any file system changes.

And this means none of those new Assets appear in the CP, even though their files actually exist.

A solution is easy:

This will clear both the Asset Container Contents and the Asset Meta caches.

Not necessarily: it depends on the work you’re doing.

As I mentioned before, caching is awesome: it helps with performance. So if you’re just running some composer updates, you wouldn’t need your deploy script to clear all of the cache contents.

On the other hand, if you’re working on the site and adding new assets outside of that environment (i.e. on your local environment), when you deploy, you need those caches cleared.

So you have two choices:

1. Run that command on every deploy, and know that you’ll have a performance hit when those caches need to be rebuilt, or

2. Manually run that command if your Assets have changed, and trust that you’ll remember to do this

Which is better? A performance hit for clearing caches even when you don’t actually need to, or having to remember to do it when you have made changes?

It depends on your site a little: if you have a massive collection of Assets especially on a remote file system (like S3, R2), that performance hit could be more costly, so you may want to only clear these caches when you absolutely need to.

On the other hand, if you have a site with local asset storage and a smaller number of assets, that performance hit is negligible.

Which you choose is up to your site, its scale, and your workflow.

Curiously though, when we do store Assets on S3/R2, this is when we are less likely to clear these caches because Assets are now no longer part of our deployment workflow: they live outside of the repository, and any changes to Assets are only made via the production CP. 

This is when we don’t want to clear the caches, as each deploy should be making zero updates to assets.

But as soon as Assets are stored in your repository, it makes more sense to have your deployment clear these asset caches.

I’ve been building Statamic sites for years, and yet this is the first time this has tripped us up.

Why is that?

These config options are newer, and our older Starter Kit, which had some cache config, did not have the Asset Container Contents (or the newer Asset Meta) caches configured.

If you’re working on a Statamic site created before 5.48.0, you are probably missing these in your config/cache.php file:

When they’re not present, Statamic would handle it inside Laravel’s default cache store. This means that when we did a new deploy, and Laravel’s cache was cleared, these caches would have been cleared too.

What Ryan’s PR does is move these two caches to separate stores – which has major advantages.

If you have thousands of Assets across dozens of gigabytes stored remotely (such as S3 or R2), the cost of rebuilding caches can be significantly noticeable. Prior to these stores, every deploy would clear the caches and give you no choice but to rebuild them.

Now though, you have a choice.

When you’re creating a new site, these cache configurations are now present in your config/cache.php file, so you’re all set - but just be aware that you may need to clear your caches on production-ready environments.

If your site has a small number of assets, you may want to include the assets:clear-cache command as part of your deployment.

But if you have a larger site, or a more complex setup, you may only want to clear those caches when you want or need to. This would allow you to update Statamic (i.e. a composer update) and redeploy the site without needing to reset all of your caches.

But that’s the key: you have the choice.

Being aware of these caches is the important part - and for many of our sites, clearing those caches will be part of the deployment process. For others, we won’t as we’re storing Assets remotely, and we actually rely on those caches persisting.

Knowing that if you have the same issue, and scratch your head as to why your assets aren’t appearing in the CP, at least you now know why, and how to work around it.