stale_404_purge

Stale 404 Purge clears stale reverse-proxy cache entries for URLs that previously returned 404 Not Found but later become valid. This helps prevent upstream caches such as Varnish from continuing to serve outdated 404 Not Found responses after content, aliases, redirects, or files change.

Features

Stale 404 Purge is a intended for sites that cache 404 Not Found responses at an upstream reverse proxy.

On high-traffic sites, caching 404 Not Found responses can reduce repeated requests for missing pages. However, a problem can occur when a URL that once returned 404 Not Found later becomes valid. The reverse proxy may continue serving the stale cached 404 Not Found response until that specific path is purged.

This module solves that problem by identifying URLs that may previously have been cached as 404 Not Found and issuing targeted purge requests when those URLs become valid.

The module currently reacts to the following events:

A node is created as published
An existing node transitions from unpublished to published
A path alias is created
A path alias is updated
A redirect is deleted
A public file becomes available

For those events, the module determines the affected path or paths and requests a targeted upstream purge, rather than requiring the entire cache to be cleared.

Common use cases include:

Sites using Varnish or another reverse proxy that caches 404 Not Found responses
Sites using the Purge ecosystem to invalidate external caches
Publishing workflows where content may appear at URLs that were previously requested before the content existed
Sites where public file URLs may be requested before the file is uploaded or made available

This module is intentionally narrow in scope. It is designed to handle stale cached 404 Not Found responses, not general-purpose cache invalidation.

Post-Installation

After installing and enabling the module, no separate configuration is required. However, you must activate the Stale 404 Purge
queuer plugin in the Purge administration interface at
`/admin/config/development/performance/purge`. Without enabling the queuer,
Purge will detect events but won't add items to the queue.

The module listens for supported entity and path events and collects affected paths automatically. When a relevant path may have transitioned from invalid to valid, the module asks the configured purge backend to invalidate that specific path.

For the module to have practical effect, your site should already have a working upstream purge mechanism. In most cases, this means that the Purge module and an appropriate reverse-proxy integration are configured correctly.

Suggested post-installation verification:

Confirm that your reverse proxy is configured to cache 404 Not Found responses
Confirm that Purge is installed and successfully invalidating external cache entries
Create a new published node with an alias and verify that the affected path is purged
Update a path alias and verify that the new path, and where applicable the old path, are purged
Delete a redirect and verify that the source path is purged

If no supported purge backend is available, the module does NOT perform destructive fallback actions such as clearing Drupal caches or flushing the entire reverse proxy cache.

Additional Requirements

Drupal core is required.

For actual upstream cache invalidation, this module is intended to work with the Purge module and a compatible reverse-proxy purge setup. Without a working external purge integration, enabling this module alone will not clear reverse-proxy caches.

The Redirect module is only required if you want the redirect deletion behavior.

Recommended modules/libraries

Purge - Provides the purge framework used to invalidate external caches
Acquia Purge - Recommended for Acquia-hosted sites using Acquia's Varnish integration
Redirect - Enables redirect deletion handling
Pathauto - Commonly used on sites where aliases are generated automatically and stale cached 404 Not Found entries are more likely to occur

Similar projects

This module is related to the broader Purge ecosystem, but it serves a narrower purpose.

Purge provides the general framework for invalidating external caches. Stale 404 Purge does not replace Purge; it identifies a specific class of paths that may need targeted invalidation.
Acquia Purge provides Acquia-specific external cache invalidation. Stale 404 Purge can complement it by identifying stale 404 Not Found paths that should be purged.
URLs Queuer and related queuer modules focus on collecting and queueing URLs for invalidation more broadly. Stale 404 Purge focuses specifically on paths that may have stale cached 404 Not Found responses after a content or path state change.

The main difference is scope: this module is intentionally small and opinionated. It is not trying to be a full cache invalidation strategy. It solves one specific operational problem.

Supporting this Module

Issue reports, testing, review, and merge requests are welcome.

If you adopt this module, feedback from real-world publishing and reverse-proxy environments is especially valuable.

Community Documentation

Additional documentation, walkthroughs, and example configurations may be added here over time.

Potential future documentation topics include:

Using the module with Purge and Varnish
Using the module with Acquia Purge
Testing stale 404 Not Found invalidation locally
Troubleshooting path alias and redirect scenarios

Limitations

This module does not clear the entire reverse-proxy cache.
This module is intended to complement an existing external purge setup, not replace one.
This module currently handles redirect deletion, but not redirect updates.
This module focuses on targeted stale 404 Not Found cleanup rather than broad cache invalidation policy.