The Problem

Must-use plugins (mu-plugins) in the wp-content/mu-plugins/ directory are supposed to load automatically on every request. In multisite installations, they may not load due to subdirectory structure issues, incorrect file naming, or loading order problems.

Symptoms

  • Mu-plugins work on main site but not on subsites
  • Functions in mu-plugins are undefined
  • Network-wide mu-plugin settings do not apply
  • Plugin code is in mu-plugins directory but does not execute

Real Error Scenario

```bash # Plugin file exists but does not load ls wp-content/mu-plugins/ network-settings/ custom-login.php

# custom-login.php loads (PHP file in root) # network-settings/ does NOT load (directory without loader) ```

Key Rule: Mu-Plugins in Subdirectories Are NOT Auto-Loaded

WordPress only loads *.php files directly in the mu-plugins/ directory. Subdirectories are ignored.

How to Fix It

Fix 1: Create a Loader File for Subdirectory Plugins

php
// wp-content/mu-plugins/load-plugins.php
<?php
// Load all mu-plugins from subdirectories
$mu_plugins = glob(WPMU_PLUGIN_DIR . '/*/*.php');
foreach ($mu_plugins as $plugin) {
  require_once $plugin;
}

Fix 2: Place PHP Files Directly in mu-plugins Directory

```bash # WRONG: Plugin in subdirectory wp-content/mu-plugins/network-settings/custom-login.php

# CORRECT: PHP file directly in mu-plugins wp-content/mu-plugins/custom-login.php ```

Fix 3: Use Plugin Naming Convention

```php // wp-content/mu-plugins/000-network-auth.php <?php /** * Plugin Name: Network Authentication * Network: true */

// This mu-plugin runs on ALL sites in the network add_action('init', function() { // Network-wide logic here }); ```

Fix 4: Site-Specific Mu-Plugins

```php // wp-content/mu-plugins/site-specific.php <?php $blog_id = get_current_blog_id();

if ($blog_id === 2) { // Only run on site with ID 2 require_once WPMU_PLUGIN_DIR . '/site-2-custom.php'; }

if (is_main_site()) { // Only run on main site require_once WPMU_PLUGIN_DIR . '/main-site-custom.php'; } ```

Fix 5: Verify Mu-Plugins Are Loading

```bash # Check loaded mu-plugins wp plugin list --status=mustuse --path=/var/www/html

# Verify file permissions ls -la wp-content/mu-plugins/ # Files should be readable by the web server user chmod 644 wp-content/mu-plugins/*.php ```

Fix 6: Debug Mu-Plugin Loading

```php // Add to the top of your mu-plugin error_log('MU-Plugin loaded: ' . __FILE__);

// Check the log tail -f /var/log/apache2/error.log | grep "MU-Plugin" ```

Fix 7: Ensure MU Plugin Directory Exists

bash
# Create mu-plugins directory if it doesn't exist
mkdir -p wp-content/mu-plugins
chown www-data:www-data wp-content/mu-plugins