Precision Caching: A Systematic Guide to Troubleshooting Stale Assets in Drupal

In complex web environments, ensuring that the latest content reaches the end user is rarely as simple as a single "refresh." This guide explores the systematic approach required to troubleshoot and resolve stale assets within a modern, high-performance architecture.

Troubleshooting Stale Assets in a Multi-Layered Stack

Developers often encounter "stale assets"—images or stylesheets that fail to update after a deployment. While the common reflex is to flush the entire site, this "sledgehammer" approach is inefficient and can cause significant performance spikes.

Instead, troubleshooting a complex stack (Akamai > Varnish > Redis > Drupal) requires a systematic "peel-the-onion" strategy. To resolve the issue without impacting site stability, you must isolate whether the stale data resides at the Edge, the Proxy, or the Application layer.

# Bypass Akamai to check Varnish/Origin directly
curl -I -H "Host: www.your-site.com" http://[ORIGIN_IP]/path/to/asset.jpg

-


The Cache Hierarchy

Isolation Workflow

To identify the "stuck" layer, test the resource at each stage moving from the inside out:

1. Application: Check the resource via a local environment or by bypassing the proxy.

2. Proxy: Use curl to check for X-Varnish headers and see if the age resets after a local purge.

3. Edge: Check X-Cache headers from Akamai to see if the CDN is serving a hit from a stale geographic POP (Point of Presence).

Would you like me to provide the specific Drush or cURL commands to selectively invalidate these individual layers?

Here is how to isolate the layer and selectively invalidate each.

1. Identify the Stale Layer (The "Header Check")

Use curl -I -v https://yourdomain.com/path/to/file to inspect headers. This is your primary diagnostic tool.

Layer-by-Layer Indicators:

Pro Tip: If you append a unique query string (e.g., ?refresh=now) and the content is correct, the problem is in Akamai or Varnish. If it is still stale, the problem is in Redis or Drupal's Internal Cache.

2. Troubleshooting & Selective Invalidation

Layer A: Akamai (The Edge)

If the query string bypass works, Akamai is holding the old version.

• Identification: Look for X-Cache: TCP_HIT.

• Invalidation: Use the Akamai Control Center (Luna) or the Akamai CLI.

  • Fast Purge (by URL): akamai purge invalidate https://yourdomain.com/file.jpg

  • By Cache Tag: If using the akamai Drupal module, it sends Edge-Cache-Tag headers.

Layer B: Varnish (The Proxy)

Varnish sits between Akamai and your server.

• Identification: Look for X-Varnish headers. If the first number is different from the second (e.g., X-Varnish: 1234 5678), it’s a hit.

• Invalidation: Use varnishadm on the server:

  Bash

  # Ban by URL path
  varnishadm "ban req.url ~ /path/to/content"
  # Ban by specific Host and URL
  varnishadm "ban req.http.host == yourdomain.com && req.url == /index.html"
  

   

Layer C: Redis (The Implementation)

If Drupal is serving stale content even when Akamai/Varnish are bypassed, Redis is likely holding the "render" or "data" cache.

• Identification: Harder to see in headers, but if X-Drupal-Cache: HIT persists after a Varnish clear, it's internal.

• Invalidation:

  Bash

  # Flush specific bin (e.g., render cache) via Drush
  drush cache:clear render
  
  # Nuclear option (Flush ALL Redis data - Use with caution!)
  redis-cli flushall
  

   

Layer D: Drupal Internal & Dynamic Cache

• Page Cache (Anonymous): Controlled by the page_cache module. Clear with drush cache:clear bin page.

• Dynamic Page Cache (Authenticated): Clear with drush cache:clear bin dynamic_page_cache.

• The "Everything" Rebuild: If you are unsure and the site is small, drush cr (cache-rebuild) clears all internal bins and Redis entries.

3. Recommended Troubleshooting Workflow

1. Check with a Query String: Does domain.com/file?any=thing show the new file?

   • Yes: Problem is Akamai or Varnish.

   • No: Problem is Drupal/Redis.

2. Verify the Purge Queue: If you use the Purge module, run drush p-queue-work. Often, deployments trigger many invalidations that get stuck in the queue.

3. Check File Metadata: For static files (CSS/JS), ensure the "Aggregate" filenames changed. Drupal 11 appends a hash (e.g., css_abc123.css). If the hash didn't change, Drupal thinks the file is the same.

Drush script to automate the clearing of these layers sequentially

Since we’re dealing with a multi-layered "sandwich" of caching, a sequential script is the best way to ensure you aren't chasing "ghost" caches.

The following Bash/Drush approach starts at the bottom (Drupal/Redis) and works its way out to the Edge (Akamai). This ensures that once the outer layers are cleared, they don't immediately re-cache stale data from an uncleared inner layer.

The "Layer-Peeler" Troubleshooting Script

You can run these commands manually or save them as a .sh file on your web server.

#!/bin/bash

# 1. CLEAR DRUPAL INTERNAL BINS (The Core)
echo "Step 1: Clearing Drupal Internal Cache Bins..."
drush cache:clear bin render
drush cache:clear bin page
drush cache:clear bin dynamic_page_cache

# 2. CLEAR REDIS (The Backend)
# If you have multiple sites on one Redis instance, use 'flushdb' carefully.
echo "Step 2: Flushing Redis..."
redis-cli flushall 

# 3. CLEAR VARNISH (The Proxy)
# This assumes varnishadm is configured on the local post.
echo "Step 3: Banning Varnish URLs..."
varnishadm "ban req.http.host ~ ." # Nuclear: Clears everything for all hosts

# 4. PROCESS PURGE QUEUE (The Bridge)
# If using the Purge module to talk to Akamai, process the backlog.
echo "Step 4: Processing Purge Queue..."
drush p-queue-work

# 5. AKAMAI MANUAL PURGE (The Edge)
# Requires Akamai CLI installed and configured.
# Replace with your specific CP Code or URL.
echo "Step 5: Triggering Akamai Fast Purge..."
akamai purge invalidate --cpcode 123456 

How to Identify "Stale" Files vs. "Stale" Pages

If your CSS/JS files specifically aren't updating, the issue is often Aggregation.

Advanced Debugging: The Header Comparison

To be 100% sure where the file is stuck, run these two commands and compare the Last-Modified or ETag headers:

1. Check Origin (Bypass Akamai/Varnish):

   curl -I -H "Host: yourdomain.com" http://localhost:8080/path/to/file

2. Check Edge (Public):

   curl -I https://yourdomain.com/path/to/file

If (1) is new and (2) is old: The issue is Akamai or Varnish.

If both are old: The issue is Drupal or Redis.

Next Step

Specific VCL (Varnish Configuration Language) snippet to ensure Varnish correctly respects Drupal's cache tags

To ensure Varnish correctly interprets the cache tags sent by Drupal 11 (via the Purge and Varnish Purge modules), your VCL (Varnish Configuration Language) needs to be able to "ban" content based on the X-Cache-Tags header.

1. The VCL Snippet (Varnish 6.x / 7.x)

Add this logic to your vcl_recv and vcl_backend_response sections. This allows Drupal to send a PURGE or BAN request that targets specific tags rather than just a single URL.

sub vcl_recv {
    # 1. Handle incoming BAN requests from Drupal
    if (req.method == "BAN") {
        if (!client.ip ~ purge_allow_list) {
            return (synth(405, "Not allowed."));
        }

        # Invalidate by Cache-Tags header sent by Drupal
        if (req.http.X-Cache-Tags) {
            ban("obj.http.X-Cache-Tags ~ " + req.http.X-Cache-Tags);
            return (synth(200, "Banned tags: " + req.http.X-Cache-Tags));
        }
        
        # Fallback to URL-based ban
        ban("obj.http.url ~ " + req.url);
        return (synth(200, "Banned URL: " + req.url));
    }
}

sub vcl_backend_response {
    # 2. Store Cache-Tags in the object so Varnish can "find" them later
    # We keep them in the object but usually hide them from the end-user in vcl_deliver
    if (beresp.http.X-Cache-Tags) {
        set beresp.http.X-Cache-Tags = beresp.http.X-Cache-Tags;
    }
}

sub vcl_deliver {
    # 3. Security: Remove the tags before the response hits Akamai/User
    # Akamai doesn't need Drupal's internal tags, it uses its own (Edge-Cache-Tag)
    unset resp.http.X-Cache-Tags;
}

2. Identifying "Stuck" Tags in Varnish

If you suspect Varnish is ignoring your purges, you can "watch" the bans in real-time. This is the best way to see if Drupal is actually talking to Varnish.

Run this on your Varnish server:

varnishlog -g request -q "ReqMethod eq 'BAN'"

If you see no output when you clear a cache in Drupal, the Purge HTTP Bundler or Varnish Purge module in Drupal is misconfigured (likely pointing to the wrong IP/Port).

3. Troubleshooting Akamai Specifics

Since you have Akamai in front, it is critical that Drupal sends two different tag headers:

1. X-Cache-Tags: For Varnish (internal).

2. Edge-Cache-Tag: For Akamai (external).

The "Refreshed File" Trap:

If a file (like logo.svg) is updated but the filename stays the same, Akamai will often ignore the Drupal cache-rebuild because it sees the same URL. You must ensure the Akamai Purge module is configured to send an invalidation request specifically for that URL or CP Code.

Checklist for Your Deployment Script

To make your troubleshooting definitive, check these three specific headers in order:

• X-Drupal-Cache-Tags: Are they present in the origin response? (If not, Drupal isn't tagging).

• X-Varnish-Cache: Does it say HIT after you just cleared it? (If so, Varnish ban failed).

• X-Akamai-Stale: Does Akamai show served-stale? (If so, Akamai is holding the file despite the origin being updated).

How to configure the Drupal "Purge" module specifically to bridge these two layers (Varnish & Akamai) simultaneously


 

# Check how many items are waiting to be sent to Akamai/Varnish
drush p-queue-stats

# Manually force the queue to work (useful after a big deployment)
drush p-queue-work

use Drupal\file\FileInterface;

/**
 * Implements hook_entity_update().
 */
function your_module_file_update(Drupal\Core\Entity\EntityInterface $entity) {
  if ($entity instanceof FileInterface) {
    // 1. Get the absolute URL of the file
    $file_url = \Drupal::service('file_url_generator')->generateAbsoluteString($entity->getFileUri());

    // 2. Get the Purge Invalidation Factory service
    $invalidation_factory = \Drupal::service('purge.invalidation.factory');
    
    // 3. Get the Purge Queue service
    $queue = \Drupal::service('purge.queue');

    // 4. Create a 'url' type invalidation (recognized by both Akamai & Varnish)
    $invalidation = $invalidation_factory->get('url', $file_url);

    // 5. Add to queue (will be processed by drush p-queue-work or cron)
    $queue->add(\Drupal::service('purge.purgers')->getPluginsEnabled(), [$invalidation]);
  }
}

curl -I -H "Pragma: akamai-x-cache-on, akamai-x-get-cache-key, akamai-x-get-true-cache-key" https://yourdomain.com/sites/default/files/important-file.pdf

# 1. Standard Drupal Update Sequence
drush deploy -y  # This runs updb, cim, cr, and deploy:hook in order

# 2. Process the Purge Queue (The "Bridge")
# This pushes the actual invalidation requests to Varnish and Akamai
echo "Processing Purge Queue..."
drush p-queue-work --max-items=500 

# 3. Optional: Direct Varnish "Nuclear" Clear 
# Only needed if you changed critical site-wide architecture (like VCL)
# varnishadm "ban req.http.host ~ ."

# 4. Verification
drush p-queue-stats

#!/bin/bash
set -e # Stop script on error

echo "--- Starting Drupal 11 Deployment ---"

# Step 1: Maintenance Mode On
drush maint:set 1

# Step 2: Deployment logic
drush deploy -y

# Step 3: Specific Purge Logic
# We run it multiple times if the queue is large to avoid timeouts
echo "Emptying Purge Queue..."
for i in {1..3}; do
  drush p-queue-work --max-items=100
  sleep 1
done

# Step 4: Maintenance Mode Off
drush maint:set 0

echo "--- Deployment & Purge Complete ---"

# Monitor all BAN and PURGE requests globally
varnishlog -g request -q 'ReqMethod eq "BAN" or ReqMethod eq "PURGE"'

# Replace 192.168.1.100 with your Drupal server's internal IP
varnishlog -g request -q 'RemoteAddr eq "192.168.1.100" and ReqMethod eq "BAN"'

// Define paths that should never be cached at any layer.
$no_cache_paths = [
  '/api/v1/user-data',
  '/checkout',
  '/cart',
  '/user/login',
  '/admin',
];

// Check current request URI.
$current_path = $_SERVER['REQUEST_URI'];

foreach ($no_cache_paths as $path) {
  if (strpos($current_path, $path) === 0) {
    // 1. Tell Drupal to skip its internal page caches.
    \Drupal\Core\Site\Settings::get('cache')['bins']['page'] = 'cache.backend.null';
    \Drupal\Core\Site\Settings::get('cache')['bins']['dynamic_page_cache'] = 'cache.backend.null';

    // 2. Force Headers for Akamai, Varnish, and Browser.
    // 'no-store' is the strongest directive (don't even save to disk).
    header('Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0, s-maxage=0');
    header('Pragma: no-cache');
    header('Expires: Thu, 01 Jan 1970 00:00:00 GMT');
    
    // 3. Signal to Akamai/Varnish to bypass specifically via an Edge header.
    header('Edge-Control: no-store');
    header('X-Accel-Buffering: no'); // Helpful for Nginx/Varnish streaming
    break;
  }
}