Home / Docs / Troubleshooting

Troubleshooting & FAQ

The questions that come up most, and how to settle them.

Troubleshooting

It loads on the command line but not in FPM / Apache

PHP has a separate configuration per SAPI. php --ri howdah working on the CLI does not mean the web server loaded it. Enable it for the running SAPI and reload that service:

# Debian/Ubuntu (Surý)
sudo phpenmod -v 8.1 howdah
sudo systemctl reload php8.1-fpm       # or: systemctl reload apache2

# then confirm against the SAPI's own config
php-fpm8.1 -i | grep -i howdah          # or check a phpinfo() page

On Apache mod_php, the module is loaded by the web server process, so reload Apache, not FPM.

The self-test is flagged but an over-limit request is not blocked

PHP's own max_input_vars (default 1000) can stop parsing before Howdah's higher max_input_vars (2000) is reached — PHP is protecting itself first, which is fine. For the multipart limits, confirm the request really crosses the limit, and that the rule is not set to detect/off in your TOML.

A request logged an event but still returned HTTP 200

Expected for the input-shape and request-header rules on some SAPIs: the offending variable is dropped and logged (the real mitigation), but the 403 is best-effort and may not land before the script has already produced output. The multipart limits, by contrast, block before the script runs. See Enforcement timing.

Nothing is being blocked at all

Check the global mode (php --ri howdah shows it). In detect mode only the Critical rules block; Standard rules log. Switch to block once the logs look clean. Confirm the log path is writable, or events will be silently lost.

Upgrading

# apt
sudo apt-get update && sudo apt-get install --only-upgrade php8.1-howdah
sudo systemctl reload php8.1-fpm
# yum / dnf
sudo yum update php81-howdah
# tarball: verify + replace howdah.so for your PHP minor, then reload

Always verify the signature of a new tarball before replacing (see the install picker). Your TOML and ini are not touched by an upgrade.

Uninstalling

# apt: stop loading but keep the package, or remove entirely
sudo phpdismod -v 8.1 howdah && sudo systemctl reload php8.1-fpm
sudo apt-get purge php8.1-howdah
# yum
sudo yum remove php81-howdah
# tarball: remove the extension=howdah.so line (or the conf.d file) and reload

Removal never breaks PHP: the package maintainer scripts only enable/disable the module and never fail the transaction.

FAQ

Does Howdah replace patching or upgrading PHP?: No. Upgrade PHP when you can. Howdah is for when you cannot, or until you can — especially on EOL PHP that will never get the official fix.
Will it break my site?: It is designed to fail open: a bug in Howdah must never crash or wedge PHP. Start in detect mode, watch the logs, then move to block. The false-positive corpus (ordinary galleries, settings forms, nested arrays) passes with zero blocks at the default limits.
Does it phone home or need a cloud service?: No. Howdah runs entirely inside your PHP. It makes no outbound connections and needs no account or external service.
Which PHP builds are supported?: Non-thread-safe (NTS) PHP 5.4 through 8.5 on Linux x86_64 and aarch64, one build per minor version. ZTS builds are not supported. See coverage for what has been tested.
What is the performance cost?: Howdah counts parts and variables as PHP already parses them; there is no second parse of the body. It adds bounded bookkeeping per request and does not buffer the whole body itself.
How do I report a security issue?: Privately, through GitHub's vulnerability reporting — see the security policy. Please do not open a public issue for a suspected vulnerability.