Complete Troubleshooting Tutorial for WordPress Wordfence's Inability to Create wordfence-waf.php

Someone mentioned that after installing Wordfence on his website, he kept getting errors saying that it couldn't create the wordfence-waf.php file in the root directory. I asked him to send me a screenshot; the error message was just one line, saying it was a file permission issue.

I thought about it for a moment, and realized I'd encountered this before. I spent ages trying to figure it out, almost thinking the hosting provider was up to something. It turned out to be a permissions and ownership issue, but the logic of the hosting control panel can be really confusing.

Let me first clarify what this wordfence-waf.php is.

It is actually the protection file of the Wordfence firewall, which must be written in the root directory of the website, at the same level as wp-config.php.

Without this file, the firewall cannot start; it's like you've installed a lock but the key can't be inserted.

Option 1: One-click permission modification via control panel (BT Panel/)HestiaCP/cPanel)

If you're using BT Panel, it's actually the simplest. Go to your website, find the corresponding site, click Settings, then go to Directory Permissions. Change the website root directory permission to 755 and all files permission to 644. Then check if the running user is "www"; if not, switch it. Click the "Repair Permissions" button, wait for it to finish, refresh Wordfence, and try again.

For HestiaCP, go to the website editing page and enable the option called "Allow write access to web root". Then run a few SSH commands to unify the owner and permissions of the website directory.

chown -R admin:www-data /home/admin/web/你的域名/public_html
chmod -R 755 /home/admin/web/你的域名/public_html
find /home/admin/web/你的域名/public_html -type f -print0 | xargs -0 chmod 644

cPanel is more intuitive. Open the file manager, turn on "Show hidden files" in the upper right corner, right-click on the directory and change the permissions to 755, change the file permissions to 644, and there is also a function to fix the file owner in the advanced options.

Option 2: Manually change permissions via SSH (general)Linux）

If the control panel can't handle it, use SSH manually. Once connected to the server, unify ownership first. In an LNMP/LEMP environment, the web runtime group is typically www-data or www.

chown -R 你的面板用户:www-data /网站根目录完全路径

Then set the folder permissions to 755 and the file permissions to 644.

find /网站根目录 -type d -print0 | xargs -0 chmod 755
find /网站根目录 -type f -print0 | xargs -0 chmod 644

After the process is complete, return to the WP backend and re-enable the firewall; it should most likely resolve the issue.

Option 3: Manually create wordfence-waf.php (a killer solution when permissions are locked)

If you can't change anything via the SSH panel, do it manually. Create a file named wordfence-waf.php in the root directory and paste the following code into it.

<?php
if (!defined('WFWAF_VERSION')) {
    define('WFWAF_VERSION', '7.11.0');
}
$wafConfig = array(
    'wafAutoPrepend' => true,
    'wafFile' => __FILE__,
    'wpContentDir' => dirname(__FILE__) . '/wp-content',
    'wpPluginsDir' => dirname(__FILE__) . '/wp-content/plugins',
    'wafLogDir' => dirname(__FILE__) . '/wp-content/wflogs',
);
require_once $wafConfig['wpPluginsDir'] . '/wordfence/lib/waf/waf.php';

Remember to replace version 7.11.0 with your current Wordfence version. Set file permissions to 644, and the owner should match the website. Then edit wp-config.php and add the following line at the very top of the file.

require_once 'wordfence-waf.php';

Save and refresh Wordfence. The firewall will automatically recognize it and no longer report errors.

Option 4: Check the rules that restrict write access.

Sometimes it's not a permissions issue, but rather the configuration file that's blocking it. Open your .htaccess file and delete all rules that restrict file write access or prevent PHP file creation. For Nginx, check your site configuration for restrictions like root path read only or create_file off, and remove them.

Another scenario is that the virtual host or lightweight cloud hosting itself restricts the generation of PHP files in the root directory. In this case, you need to contact your hosting provider to remove the restriction, or switch the protection mode of Wordfence. Go to the Wordfence menu, All Options, WAF, and change the protection engine mode to Extended Protection to bypass root file creation.

Solution 5: Plugin conflicts causing blocking

Some caching or security plugins may block this operation. Temporarily disable caching plugins like WP Rocket, W3 Total Cache, and LiteSpeed ​​Cache, as well as security plugins like Sucuri and iThemes Security. Then clear the server cache and opcache, and restart the PHP service.

systemctl restart php8.3-fpm

Quick troubleshooting sequence (it is recommended to follow the steps in order)

I suggest you follow this order to avoid messing around. First, unify permissions and ownership; this has the highest probability of solving the problem. If that doesn't work, restart PHP-FPM and refresh the backend. If that still doesn't work, manually create a new file and modify wp-config. Then check if your Nginx or Apache configuration is blocking the creation of new PHP files in the root directory. Finally, consider switching firewall modes.

One thing I must remind you of is that you should never set permissions to 777. Folder permissions should be 755 and file permissions 644; that's the standard. Setting permissions to 777 will directly expose your website, posing an extremely high security risk. If you get hacked, it will be too late to regret it.

To be honest, I'm not sure if these solutions will work for your situation, but I've shared the pitfalls I encountered and the methods I figured out. If you get any other error messages, take a screenshot and send it to me, and I'll take another look.

Since you've read this far, if you found it helpful, please like and share it. If you want to receive updates first, you can also follow me!

Thank you for reading my article. See you next time.