Below is a step-by-step guide on how to fix the “Primary script unknown” FastCGI errors when a doc_root value is missing or empty in a cPanel + CloudLinux environment running PHP-FPM.

Overview

In cPanel-based PHP-FPM configurations, each domain gets its own pool file under:

/opt/cpanel/ea-phpXX/root/etc/php-fpm.d/

If php_value[doc_root] is set to an empty string (""), PHP-FPM cannot locate the actual script path, triggering FastCGI errors like:

AH01071: Got error 'Primary script unknown'

You may also see other warnings such as:

AH01067: Failed to read FastCGI header

To fix this, you must ensure that doc_root is correctly set for the domain’s PHP-FPM pool configuration.

Symptoms

1. Intermittent or persistent “Primary script unknown” errors in Apache’s error log (/usr/local/apache/logs/error_log).

2. WHMCS or other PHP-based sites failing to load or showing 5xx errors.

3. Checking the pool config file reveals:

   cat /opt/cpanel/ea-php81/root/etc/php-fpm.d/example.com.conf | grep doc_root
   php_value[doc_root] = ""
   

Solution Steps

Below is a proven method to directly set doc_root in the domain-level .php-fpm.yaml file, thereby instructing cPanel to generate a correct FPM config.

1. Verify the Domain’s Document Root

First, confirm cPanel’s recognized document root:

cat /var/cpanel/userdata/exampleuser/example.com | grep documentroot

• Example output:

  documentroot: /home/exampleuser/public_html
  

• Ensure this matches the actual path where the domain’s site files are located.

2. Check the Existing Pool Configuration

Look for the empty doc_root in your FPM pool file:

cat /opt/cpanel/ea-php81/root/etc/php-fpm.d/example.com.conf | grep doc_root

If it shows:

php_value[doc_root] = ""

then doc_root is not being set properly.

3. Edit the Domain’s .php-fpm.yaml File

In cPanel, per-domain FPM settings often take precedence over global or system overrides. So the cleanest fix is to explicitly add a doc_root setting to the domain’s .php-fpm.yaml file.

1. Open (or create) /var/cpanel/userdata/exampleuser/example.com.php-fpm.yaml. For instance:

   nano /var/cpanel/userdata/exampleuser/example.com.php-fpm.yaml
   

2. Insert the following lines:

   ---
   _is_present: 1
   php_value_doc_root: "/home/exampleuser/public_html"
   

   • php_value_doc_root must match the actual path from step #1.

   • The _is_present: 1 line indicates that the domain is configured for PHP-FPM in cPanel.

3. Save and exit.

4. Rebuild the PHP-FPM Configuration

Run the cPanel rebuild script and restart services:

/scripts/php_fpm_config --rebuild
systemctl restart ea-php81-php-fpm
systemctl restart httpd

(Adjust PHP version if necessary. For example, use ea-php80 or ea-php82.)

5. Confirm doc_root Is Now Properly Set

Re-check the final FPM config file:

cat /opt/cpanel/ea-php81/root/etc/php-fpm.d/example.com.conf | grep doc_root

You should see something like:

php_value[doc_root] = /home/exampleuser/public_html

If so, PHP-FPM can now locate scripts correctly, and “Primary script unknown” errors should stop.

6. Verify in Apache Error Logs

Keep a real-time watch on Apache’s main error log while visiting the domain or running your WHMCS site:

tail -f /usr/local/apache/logs/error_log

• If you see no new AH01071 or Primary script unknown lines, the fix is successful.

• You may also check any domain-specific logs if applicable (though cPanel often consolidates them in the main error log for PHP-FPM issues).

FAQ

Q1. Why use example.com.php-fpm.yaml instead of /var/cpanel/ApachePHPFPM/system_pool_overrides/?
A: Sometimes cPanel actively enforces an empty doc_root from the domain’s .php-fpm.yaml or internal settings. Domain-level YAML files override generic system/user overrides. By setting php_value_doc_root directly in .php-fpm.yaml, you ensure cPanel’s own process includes the correct doc_root in the final .conf file.

Q2. What if I already tried system_pool_overrides/*.yaml and it didn’t work?
A: That likely means domain-level config or cPanel’s caching was overriding your custom setting. The domain’s .php-fpm.yaml approach solves this by leveraging cPanel’s “native” logic.

Q3. Do I need to keep _is_present: 1?
A: Yes—this flag tells cPanel that PHP-FPM should remain enabled for that domain. If you remove it, cPanel might consider disabling FPM or ignoring the file.

Q4. Will this setting persist through cPanel updates?
A: Yes. Any .php-fpm.yaml file in /var/cpanel/userdata/exampleuser/ is generally preserved. However, if you disable and re-enable PHP-FPM via WHM, re-check to ensure the file remains intact.

Q5. Still seeing errors?
A:

1. Make sure there aren’t conflicting directives in an SSL-specific file (example.com_SSL.php-fpm.yaml).

2. Verify no additional includes in the final .conf forcibly setting doc_root = "".

3. Check that the domain is truly using /home/exampleuser/public_html (or another path).

4. As a last resort, rename or remove all domain-specific .php-fpm.yaml files, disable FPM in MultiPHP Manager, rebuild, then re-enable FPM and re-add the config lines.

Conclusion

By directly defining php_value_doc_root in the domain’s .php-fpm.yaml, you ensure cPanel places a correct doc_root value in example.com.conf. This solves the “Primary script unknown” FastCGI error, allowing your WHMCS or other PHP applications to run smoothly.

Key Steps Recap:

1. Check the actual docroot in /var/cpanel/userdata/exampleuser/example.com.

2. Edit /var/cpanel/userdata/exampleuser/example.com.php-fpm.yaml.

3. Add php_value_doc_root: "/home/exampleuser/public_html".

4. Rebuild configs, restart services, confirm logs are clean.

With these adjustments, you should no longer experience “Primary script unknown” or other FastCGI docroot-related issues.