Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Apache logs mod_fcgid: ap_pass_brigade failed in handle_request_ipc function

Errormod_fcgid: ap_pass_brigade failed in handle_request_ipc function

Short answer

mod_fcgid logs this when it fails to pass the PHP response on to the client, and returns a 500. The failure usually starts on the FastCGI side, and mod_fcgid logs the real reason just before it. Read those lines: a read timeout points to FcgidIOTimeout, a closed connection to a PHP process that ended.

  • Applies to Apache 2.4, mod_fcgid 2.3, PHP 8.3 with php-cgi
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the Apache error log and read the lines just before the ap_pass_brigade warning. mod_fcgid writes the reason it could not read from PHP first; that line tells you which cause below applies.

    grep -R "ErrorLog" /etc/apache2 /etc/httpd 2>/dev/null
    sudo grep -n -B4 "ap_pass_brigade failed" /var/log/apache2/error.log | tail -n 40
  2. 2Match what you see, then jump to its fix

    1. 1mod_fcgid: read data timeout in 40 seconds, then the ap_pass_brigade line, for a slow report, export or importPHP stays silent for longer than FcgidIOTimeoutFix
    2. 2mod_fcgid: error reading data, FastCGI server closed connection, or another read error from the FastCGI server, on a request that works when you repeat itThe PHP process ended while mod_fcgid was using itFix

What does the error look like?

  • mod_fcgid: ap_pass_brigade failed in handle_request_ipc function
  • mod_fcgid: read data timeout in 40 seconds
  • mod_fcgid: error reading data, FastCGI server closed connection
  • 500 Internal Server Error

Cause 1 of 2

PHP stays silent for longer than FcgidIOTimeout

1Check

FcgidIOTimeout is the longest time mod_fcgid waits to read from or write to the application, and the application must start producing its response within that time. The default is 40 seconds. Compare it with how long the failing request runs, and see whether a higher value is already set.

grep -R -n -E "FcgidIOTimeout|FcgidBusyTimeout" /etc/apache2 /etc/httpd 2>/dev/null

2Fix

Raise FcgidIOTimeout above the longest quiet stretch of the request, and keep FcgidBusyTimeout, the limit for a whole request, higher still. Better yet, make the script send its first output sooner.

# Apache server or virtual host configuration
FcgidIOTimeout 120
FcgidBusyTimeout 300

3Verify

Reload Apache and repeat the slow request; the read timeout line no longer appears in the error log.

sudo systemctl reload apache2
sudo tail -n 20 /var/log/apache2/error.log

Confirmed by httpd.apache.org

Did this fix it?

Cause 2 of 2

The PHP process ended while mod_fcgid was using it

1Check

By default a PHP FastCGI process exits after 500 requests. It can exit after mod_fcgid has already connected and sent the next request, which logs an error and returns a 500. A request that runs longer than FcgidBusyTimeout, 300 seconds by default, can be terminated as well. Look at the request limits.

grep -R -n -E "PHP_FCGI_MAX_REQUESTS|FcgidMaxRequestsPerProcess" /etc/apache2 /etc/httpd /usr/local/bin 2>/dev/null

2Fix

Set PHP's request limit and mod_fcgid's limit together, with the Apache value equal or lower, so mod_fcgid retires a process before PHP does. The documentation shows a wrapper script for the PHP side. Raise FcgidBusyTimeout if a legitimate request runs past 300 seconds.

# Apache configuration
FcgidMaxRequestsPerProcess 10000

# /usr/local/bin/php-wrapper
PHP_FCGI_MAX_REQUESTS=10000
export PHP_FCGI_MAX_REQUESTS
exec /usr/local/bin/php-cgi

3Verify

Restart Apache, send more requests than the old limit, and check that the closed connection line does not return.

sudo systemctl restart apache2
for i in $(seq 1 600); do curl -s -o /dev/null -w "%{http_code}\n" https://example.com/; done | sort | uniq -c

Confirmed by httpd.apache.org

Did this fix it?

How do I stop it coming back?

  • Pick FcgidIOTimeout from the slowest real request, not from the default, and keep FcgidBusyTimeout above it.
  • Always change PHP_FCGI_MAX_REQUESTS and FcgidMaxRequestsPerProcess together, and keep the Apache value equal or lower.
  • Leave PHP_FCGI_CHILDREN at 0: the mod_fcgid documentation says PHP's own child process management should always be disabled with it.
  • Move long exports and imports into a background job, so no web request depends on a timeout.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.