When managing a WordPress multisite installation, one might encounter an odd issue: logos and media files uploaded to the main site display correctly, but the same media causes 404 errors on subsites. This issue is not only frustrating but can also impact the overall visual integrity of subsites. A common solution lies in how site URL and home URL are handled in WordPress multisite environments, especially through rewrite rules or constant overrides.
TL;DR
Media showing on the main WordPress multisite but causing 404 errors on subsites frequently stems from base URL mismatches and WordPress rewrite limitations. Subsite media often inherits incorrect paths due to how siteurl and home values are configured. By programmatically rewriting the BASE URL using constants or filters, admins can fix the media access across all subsites. This normalization ensures consistent access to uploaded media files across the network.
Understanding the Multisite Media Challenge
WordPress multisite allows administrators to run multiple sites from a single WordPress installation. Each subsite acts like an independent site but shares a common codebase, plugins, and themes. Despite these shared resources, media management presents unique challenges in multisite environments, especially regarding how file URLs are generated and resolved.
Initially, everything might look fine when uploading a logo or image through the WordPress Customizer or Media Library on the main site. The file is accessible, typically residing in the /wp-content/uploads/sites/1 directory. Subsites, however, might point to similar locations like /sites/2, /sites/3, etc. But sometimes, instead of correctly linking these resources, a subsite may attempt to access media using the wrong domain or path, leading to 404 errors.
Why does this happen, and more importantly, how can it be fixed?
Root Cause: Misaligned Paths and URL Base Confusion
At the core of this problem is WordPress’s reliance on constants and database values to generate URLs. These constants include:
- SITEURL – The system URL that WordPress uses to load core assets and plugins.
- HOME – The frontend-accessible URL that users visit in their browsers.
In a properly functioning multisite setup, these values should adapt based on the subsite’s domain or path. But in practice, especially for subsites in domain mapping or subdirectory mode, these values may default to the main site’s context. When this happens, media file URLs generated on subsites may try reaching files based on incorrect base URLs — and hence, 404 errors result.
[p ai-img]wordpress, multisite, media error, 404 page[/ai-img]
For example, a logo uploaded to a subsite might be assigned a URL like:
https://mainsite.com/wp-content/uploads/sites/3/logo.pngHowever, if the subsite is accessed via https://subsite.example.com, and that domain is not configured to recognize and serve files from the correct path, the server throws a 404 error.
PHP Constants and Programmatic Fixes
To repair or prevent such issues, developers have used a combination of constants declared in wp-config.php and WordPress hooks to dynamically rewrite how media paths are generated. One of the most common strategies includes overriding the siteurl and home values using filters like site_url and content_url.
Using Rewrite Rules and Constants
Developers can normalize media access by doing the following in their theme’s functions.php or as part of a network plugin:
add_filter( 'upload_dir', 'fix_multisite_media_paths' );
function fix_multisite_media_paths( $uploads ) {
if ( is_multisite() ) {
$current_blog_id = get_current_blog_id();
$uploads['baseurl'] = get_site_url( $current_blog_id ) . '/wp-content/uploads/sites/' . $current_blog_id;
}
return $uploads;
}
This filter explicitly recalculates media paths to reflect the subsite’s actual directory and domain.
Alternatively, you can define constants in wp-config.php for forced overrides:
define('WP_HOME','http://subsite.example.com');
define('WP_SITEURL','http://subsite.example.com');
However, this approach may not scale well for dynamically hosted or mapped sites, which is why hooks are commonly preferred in large multisite environments.
How the Rewrite Normalizes Media Access
The rewrite filter effectively tells WordPress: for the current subsite, regardless of the main site’s configuration, generate URLs and resolve files relative to this correct context and domain. By rewriting upload_dir paths and correcting baseurl, subsites stop referencing media through the main site’s domain, eliminating 404 errors.
It’s important this rewrite logic takes into account:
- The subsite’s unique blog ID
- Whether it’s a subdomain or subdirectory multisite configuration
- Custom domain mapping (common in real-world networks)
[h2-img]wordpress admin, php code, media upload, multisite network[/ai-img]
Aside from logo issues, such fixes also resolve broken featured images, background images, and any media inserted via post editors.
Additional Measures for Persistent Problems
In some cases, server configurations might interfere with media delivery. If subsites use SSL certificates, file permissions or symlinks might break access paths. Additionally, caching plugins, CDN settings, or NGINX rewrites may require reconfiguration to reflect media path rewrites properly.
A few practical steps to consider:
- Flush rewrite rules – Go to Settings > Permalinks and click “Save” to refresh rules.
- Check .htaccess and NGINX rules – Ensure proper white-labeling per subsite.
- Use multisite-capable CDN plugins for consistent asset delivery.
Conclusion
Fixing media access issues in WordPress multisite setups isn’t just about correcting logo paths—it’s about understanding how WordPress generates URLs and how subsites diverge in context. By using programmatic rewrites and checking configuration constants, site administrators can ensure a uniform media experience network-wide. In the end, a proactive approach to URL normalization not only fixes 404s but boosts the reliability and user confidence in all subsites.
Frequently Asked Questions (FAQ)
- Q: Why does my subsite logo return a 404, but the main site logo works?
A: The subsite is likely inheriting an incorrect media URL based on the main site’s domain. This causes WordPress to look in the wrong uploads directory. - Q: Can I fix this with a plugin?
A: Some network admin plugins help manage URLs and domain mapping, but the most reliable fix is to programmatically update theupload_dirwith a proper base URL. - Q: What’s the difference between siteurl and home URL?
A: siteurl is for internal site functions and assets, whereas home is the public-facing URL. Both must match or dynamically adjust for multisite subsites. - Q: Do domain-mapped subsites face more of these issues?
A: Yes, because WordPress sometimes generates media paths relative to the primary domain unless explicitly told otherwise. - Q: Will this affect media already uploaded?
A: The fix affects how URLs are generated moving forward. Media already linked incorrectly may need manual re-linking in posts or custom fields.
