Fix crash when WordPress falls back to FTP filesystem#2974
Merged
Conversation
Centralize filesystem access in Cache\File with get_filesystem() and delete_directory() helpers. The core fix: WP_Filesystem() can return false on failure but still set $wp_filesystem to a broken FTP object. The new helper checks the return value and nulls the global on failure, preventing fatal errors from calling methods on a non-functional object. Also adds a per-request failure flag to skip repeated init attempts and a Site Health warning to guide admins toward fixing or disabling caching.
There was a problem hiding this comment.
Pull request overview
This PR fixes a critical crash that occurs on servers where WordPress falls back to FTP filesystem access instead of direct file access. The issue (#2972) manifested as fatal errors when the plugin attempted to cache remote avatars, causing entire pages to crash with "There has been a critical error on this website."
Changes:
- Centralized filesystem access in
Cache\Filewith proper handling ofWP_Filesystem()failures - Added Site Health warning to inform admins when direct filesystem access is unavailable
- Removed duplicated filesystem code from
Cache\Mediaby leveraging inherited methods
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| includes/cache/class-file.php | Added centralized get_filesystem() and delete_directory() helpers with failure handling and per-request failure flag; refactored existing filesystem initialization calls to use the new helpers |
| includes/cache/class-media.php | Removed duplicated cache_url() method in favor of inherited get_or_cache(); simplified invalidate_comment() to use centralized delete_directory() |
| includes/class-attachments.php | Fixed filesystem initialization to properly handle WP_Filesystem() failure by nulling the global on failure |
| includes/wp-admin/class-health-check.php | Added new test_filesystem() health check that warns administrators when direct filesystem access is unavailable and provides guidance on fixing or disabling caching |
| .github/changelog/fix-filesystem-graceful-failure | Added changelog entry for patch-level bug fix |
Skip the test when ACTIVITYPUB_DISABLE_REMOTE_CACHE is set, and null the broken $wp_filesystem global on failure to avoid side effects for other health checks running in the same request.
WordPress core uses native PHP functions (rename, copy, etc.) for file operations in the uploads directory — not WP_Filesystem. WP_Filesystem checks write access to ABSPATH and falls back to FTP when that fails, even though the uploads directory itself is writable. This removes all WP_Filesystem usage from cache, attachments, and CLI code, matching how core handles files in the same directory. This eliminates the FTP fallback crash entirely rather than just handling it gracefully. The health check now tests uploads directory writability instead of WP_Filesystem availability.
Instantiate WP_Filesystem_Direct explicitly to get WordPress's own filesystem methods (move, copy, rmdir) without the FTP fallback that WP_Filesystem() triggers. Cleaner than raw rename/copy/rmdir calls and leverages WP_Filesystem_Direct's recursive rmdir.
jeherve
approved these changes
Feb 25, 2026
Member
jeherve
left a comment
jeherve
left a comment
There was a problem hiding this comment.
This is looking good to me. 🚢
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2972
Proposed changes:
Cache\Filewithget_filesystem()anddelete_directory()helpers that properly handleWP_Filesystem()failure (returnsfalsebut still sets$wp_filesystemto a broken FTP object).Cache\Media(cache_url()method) by using inheritedget_or_cache().ACTIVITYPUB_DISABLE_REMOTE_CACHE.Other information:
Testing instructions:
npm run env-testdefine( 'FS_METHOD', 'ftpext' );towp-config.php— Site Health should show a "recommended" warning with instructions.Changelog entry
Changelog Entry Details
Significance
Type
Message
Fix a crash on servers where WordPress uses FTP instead of direct file access for media caching.