“Uncaught ValueError: Path cannot be empty” in WordPress: what it means and the fix
Short answer
It’s a fatal error from PHP 8: a plugin or theme asks PHP to open a file, with an empty file name, typically a setting left blank. PHP 7.4 only warned (“Filename cannot be empty”), returned nothing and let the page continue; PHP 8 throws a ValueError and the page stops. From PHP 8.4 the message reads “Path must not be empty”. Fill in the setting the plugin expects if you know it; otherwise update the plugin or send the message to its developer. The developer fix is to check the file name before opening it.
The message, on PHP 7.4, 8.0 and 8.4
An email-templates plugin loads a template from a file whose name comes from a setting. The setting was left empty:
wp-content/plugins/email-templates/email-templates.php
<?php
$template = ''; // the setting "template file" was left empty
$html = file_get_contents($template);
echo "Template loaded\n";
Warning: file_get_contents(): Filename cannot be empty in /var/www/html/wp-content/plugins/email-templates/email-templates.php on line 3
Template loadedFatal error: Uncaught ValueError: Path cannot be empty in /var/www/html/wp-content/plugins/email-templates/email-templates.php:3
Stack trace:
#0 /var/www/html/wp-content/plugins/email-templates/email-templates.php(3): file_get_contents('')
#1 {main}
thrown in /var/www/html/wp-content/plugins/email-templates/email-templates.php on line 3Fatal error: Uncaught ValueError: Path must not be empty in /var/www/html/wp-content/plugins/email-templates/email-templates.php:3
Stack trace:
#0 /var/www/html/wp-content/plugins/email-templates/email-templates.php(3): file_get_contents('')
#1 {main}
thrown in /var/www/html/wp-content/plugins/email-templates/email-templates.php on line 3On PHP 7.4 the page continues with an empty template, which may already have meant blank emails. On PHP 8 it stops: on a website that’s WordPress’s critical error page.
What a ValueError is
PHP 8 made built-in functions strict about what they’re given. php.net: “A ValueError is thrown when the type of an argument is correct but its value is incorrect.” Its own examples include “passing an empty string/array when the function expects it to not be empty.” (php.net)
Here the type is right (a text) but the value isn’t (an empty text). Before PHP 8, built-in functions often answered such cases with a warning and a return value of false or null, as in both examples on this page, and the code went on with that.
Another one: “Unknown format specifier”
The same change hits sprintf() and printf(), which plugins use for texts with placeholders such as %s. A plain % sign in such a text, like “20%”, is read as the start of a placeholder:
wp-content/plugins/sale-banner/sale-banner.php
<?php
$product = 'shoes';
echo sprintf('Save 20% today on %s', $product), "\n";
Warning: sprintf(): Too few arguments in /var/www/html/wp-content/plugins/sale-banner/sale-banner.php on line 3Fatal error: Uncaught ValueError: Unknown format specifier "t" in /var/www/html/wp-content/plugins/sale-banner/sale-banner.php:3
Stack trace:
#0 /var/www/html/wp-content/plugins/sale-banner/sale-banner.php(3): sprintf('Save 20% today ...', 'shoes')
#1 {main}
thrown in /var/www/html/wp-content/plugins/sale-banner/sale-banner.php on line 3PHP 7.4 warned and printed nothing at all for that line; PHP 8 stops the page. The letter in the message is the character after the %. In translations, the same happens when a translated text contains a % the original didn’t.
Who fixes it
- Site down? Switch PHP back or pause the plugin, as in the critical error guide.
- Find the plugin or theme from the path in the message.
- Look at its settings for a file, template or path field that’s empty, especially after a migration or a settings change, and fill it in.
- Otherwise, update it, or send the full message to its developer.
Can a check find it before the upgrade?
Not for the empty path: whether a setting is empty depends on each site, so CompatNav doesn’t report it, and our scan of both examples above found nothing. Your PHP 7.4 log can: search it for “Filename cannot be empty” and “sprintf(): Too few arguments”. Each of those lines becomes a fatal error on PHP 8. Finding PHP notices on real visits covers collecting them on a live site.
Key takeaways
- PHP 8.0 to 8.3: “Path cannot be empty”. PHP 8.4 and later: “Path must not be empty”. Same cause.
- PHP 7.4 wrote a warning, “Filename cannot be empty”, and continued; PHP 8 stops the page.
- The usual cause is a setting or option that holds an empty file name.
- Other ValueErrors from the same PHP 8 change, such as “Unknown format specifier”, work the same way.
- The developer fix: check that the name isn’t empty and the file is readable before opening it.
Frequently asked questions
Can I fix it without a developer?
Sometimes: if the error appeared after you changed a plugin’s settings, or after a migration, look for a file or template field left empty in that plugin’s settings and fill it in. Otherwise, update the plugin or contact its developer.
Why did it work before the PHP upgrade?
It didn’t really: PHP 7.4 refused the empty name too, but only with a warning, and returned nothing. The page carried on without the file’s content. PHP 8 stops instead.
Is “Path must not be empty” a different error?
No. It’s the same ValueError, reworded in PHP 8.4. Our tests show “cannot be empty” on PHP 8.0 to 8.3 and “must not be empty” on 8.4 and later.
Check your own site before you upgrade
CompatNav is a free WordPress plugin. It reads the code of your plugins and themes on your own server and tells you, in plain words, what will break and what will only show notices on the PHP version you choose. It never changes your code. It can’t see problems that only appear while code runs with real data, so a quick check of your site after the upgrade still matters.
Sources
About the code examples: each output is the real output of the code shown, run with the official PHP builds, without a php.ini, with all errors reported and displayed. Only the file path was replaced by a neutral server path.