Magento Cache Internals Explained (Filesystem View)

1. Problem Symptoms

When working with Magento performance, developers often face confusion around filesystem cache behavior, such as:

Not understanding how Full Page Cache (FPC) is stored on disk
Difficulty identifying what files control cache validity
Confusion about how Magento invalidates cache after product updates
Assumptions that Magento maintains logical “valid/invalid” flags per product
Trouble debugging cache hits vs misses

These symptoms usually arise when trying to debug performance at the file level inside var/cache/.

2. Diagnostics / Explanation

Let’s understand how Magento filesystem cache works using an example:

Cache stored in var/cache/
Product ID = 123
Filesystem cache backend

Magento relies on three key file types.

1️⃣ Tag Mapping File

Example:
var/cache/mage-tags/mage—catalog_product_123

Contents:

FPC_84f9d6c1e2a3b4c5

FPC_29c1e3a7d8f9b4c5

Purpose:
Maps a tag to cache IDs.

catalog_product_123 → cache IDs

This file does not store cache data only mappings.

2️⃣ Cache Data File

Example:
var/cache/8/4/FPC_84f9d6c1e2a3b4c5

Purpose:
Contains the actual cached HTML (e.g., PDP content).
This is the file served to users on cache hits.

3️⃣ Cache Metadata File

Example:
var/cache/8/4/FPC_84f9d6c1e2a3b4c5.meta

Contents:

created_at: 1707890000

expire_at: 1707893600

lifetime: 3600

tags:

– catalog_product_123

– catalog_category_45

Purpose:
Controls TTL and expiration logic.

How Magento Checks Cache

When a user opens Product 123:

Magento locates the cache ID
Reads the .meta file
Checks expiration: current_time > expire_at ?

If expired:

Deletes data file
Deletes metadata file
Treats request as cache miss

If not expired:

Serves cache file

What Happens When Product 123 Is Updated?

Magento cleans cache by tag.

Step 1: Read Tag File

var/cache/mage-tags/mage—catalog_product_123
Fetch all related cache IDs.

Step 2: Delete Cache Data Files

Example:

var/cache/8/4/FPC_84f9d6c1e2a3b4c5

var/cache/8/4/FPC_29c1e3a7d8f9b4c5

Step 3: Delete Metadata Files

FPC_84f9d6c1e2a3b4c5.meta

FPC_29c1e3a7d8f9b4c5.meta

Step 4: Remove Tag Mapping File

var/cache/mage-tags/mage—catalog_product_123

3. Solution

To correctly understand and debug Magento filesystem cache:

Recognize that cache validity is based on file existence, not logical flags
Use .meta files to inspect TTL and expiration
Use tag files to understand invalidation relationships
When debugging invalidation, track:
1. Tag mapping files
2. Cache data files
3. Metadata files