The Garbage Collector, In Detail

By Nawawi Jamili · 5 November 2026 · 4 min read

Docket Cache keeps its cache as files on disk. Files are added all the time, but nothing in WordPress ever removes them. That is the job of the garbage collector. This post explains what it checks, in what order, and how you can see what it did.

When it runs#

The garbage collector is a WordPress scheduled task called docketcache_gc. It runs every 5 minutes, as long as WP-Cron can run on your site. If WP-Cron is turned off, or your host blocks it, Cronbot or a cron job from your host can start it instead.

You can also run it yourself.

With WP-CLI, run wp cache run:gc.
In the admin, turn on the Garbage Collector Action Button option in Docket Cache > Configuration. A Run Garbage Collector button then appears on the Overview screen.

Only one garbage collector runs at a time. If it is already running, a second one stops straight away. It also stops when it runs out of time, usually after 3 minutes, and starts again from the beginning on the next run.

What it checks#

The garbage collector goes through the cache folder one file at a time. For each file, it asks these questions in order. As soon as one answer is yes, it removes the file and moves on to the next one.

For each cache file, the garbage collector asks six questions in order. Is the file empty? Is it too old? Are there too many files? Is the cache too big? Has the item expired? Is it stale? If any answer is yes, the file is removed. If all are no, the file is kept. — The checks, in order

Is the file empty? When a cached item expires, Docket Cache empties its file by default, instead of deleting it. Empty files are removed here.
Is it too old? No cache file is kept longer than DOCKET_CACHE_MAXTTL, which is 4 days by default.
Are there too many files? Once the cache has more files than DOCKET_CACHE_MAXFILE, 50,000 by default, the rest are removed. On large limits, it keeps 1,000 files of room below the limit.
Is the cache too big? Once the files add up to more than DOCKET_CACHE_MAXSIZE_DISK, 500 MB by default, the rest are removed.
Has the item expired? If the code that saved the item gave it an expiry time, and that time has passed, the file is removed. It looks 5 minutes ahead, so an item that is about to expire is removed now and not left until the next run.
Is it stale? This check only runs when the Auto Remove Stale Cache option is on. See the next section.

If all the answers are no, the file is kept.

Checks 3 and 4 remove files in the order the garbage collector finds them on disk, not the oldest first. They only matter when the cache is over its limits.

Stale cache#

WordPress caches the results of its own database queries, such as lists of posts, terms and comments. Each result is saved with a "last changed" time for its group. When you publish or edit a post, WordPress updates that time, and from then on it ignores the older results.

But the older results are not removed. They stay in the cache until they reach their maximum age. WooCommerce does the same with products, orders, coupons and some other data. On a busy shop, this can be many files.

With Auto Remove Stale Cache turned on, the garbage collector compares each of these files with the current "last changed" time, and removes the ones that WordPress or WooCommerce will never use again. It is off by default. Turn it on in Docket Cache > Configuration, or with DOCKET_CACHE_FLUSH_STALECACHE in wp-config.php.

After the files#

When it has gone through every file, the garbage collector does two more things.

It deletes expired transients from the database. WordPress normally does this once a day.
It saves the cache statistics. These are the numbers you see under Object Cache Stats on the Overview screen.

Reading the result#

This is the output of wp cache run:gc on one of our test sites.

-----------------------------------:----------
Cache MaxTTL                       : 345600
Cache File Limit                   : 50000
Cache Disk Limit                   : 500M
-----------------------------------:----------
Cleanup Cache MaxTTL               : 0
Cleanup Cache File Limit           : 0
Cleanup Cache Disk Limit           : 0
-----------------------------------:----------
Total Cache Cleanup                : 0
Total Cache Ignored                : 0
Total Cache File                   : 77
-----------------------------------:----------
Success: Executing the garbage collector completed.

The first three lines are your limits. 345600 seconds is 4 days.
Cleanup Cache MaxTTL counts files removed because they were too old.
Cleanup Cache File Limit and Cleanup Cache Disk Limit count files removed because the cache was over a limit.
Total Cache Cleanup adds up every file removed, including expired and stale files.
Total Cache File is the number of files kept.

On a healthy site, the cleanup numbers are small, and often zero. If Cleanup Cache File Limit or Cleanup Cache Disk Limit is high every time, the cache keeps hitting its limits. You can raise them, or keep fewer items in the cache. Our post Docket Cache On Shared Hosting explains which settings to change.

The Constants page lists every limit, and our post Managing Docket Cache With WP-CLI shows the other maintenance commands.