You ran sudo systemctl restart php8.3-fpm on an Ubuntu or Debian server and got Failed to restart php8.3-fpm.service: Unit php8.3-fpm.service not found. back. Or systemctl status php8.3-fpm answered Unit php8.3-fpm.service could not be found. It usually happens right after you reinstalled PHP, ran a release upgrade that changed the PHP version, or switched package sources, while the WordPress site returns 502 or 503 errors. Check four things in this order, because one of them is almost always the cause. Is PHP 8.3 there, is its -fpm package installed, is the unit masked, and does the web server still point at the old version’s socket?
What you’ll accomplish
- See which PHP versions and PHP-FPM services the server really has, instead of the ones you expect.
- Reinstall
php8.3-fpmwith the same extensions the site used before, taken from the old version’s package list. - Move any custom pool settings from the old version to the new one.
- Point nginx or Apache at the new socket and reload both services in a safe order.
- Confirm that a WordPress page returns
200and is served by PHP 8.3 through PHP-FPM.
Prerequisites
- Root or
sudoaccess over SSH to an Ubuntu or Debian server that runs WordPress behind nginx or Apache. - The examples use PHP 8.3 as the version you want and PHP 8.1 as the old one. That is the pair you get after
do-release-upgradefrom Ubuntu 22.04, which ships PHP 8.1, to Ubuntu 24.04, which ships PHP 8.3. Debian 12 ships PHP 8.2. Replace the numbers with your own. - If you add PHP versions from a third-party source, that is the ondrej/php PPA (a personal package archive) on Ubuntu or packages.sury.org on Debian. Both are maintained by the same person.
- A recent backup of the site files and database. Nothing below deletes site data, but a release upgrade that removed PHP may have changed other things too.
- This is the recovery path. For a first install, see installing PHP-FPM on Ubuntu.
How it works
On Debian and Ubuntu, each PHP version has its own FPM service. PHP-FPM, the FastCGI Process Manager, keeps PHP workers running so the web server can hand them requests. The package php8.3-fpm installs the unit file php8.3-fpm.service, the binary php-fpm8.3, the configuration under /etc/php/8.3/fpm/ and, once started, the socket /run/php/php8.3-fpm.sock. A socket here is a special file that nginx or Apache opens to talk to PHP. There is no unversioned php-fpm.service on these systems, so that name is never found either.
Installing php8.3 or php8.3-cli does not give you the service. Only the -fpm package does. The php-fpm package is a metapackage, an empty package that pulls in whichever version the package source treats as its default. From Ubuntu 24.04’s own archive that is php8.3-fpm. From the ondrej/php PPA it is usually the newest PHP release, which may not be 8.3.
When a package is removed but not purged, dpkg keeps its configuration files and marks it rc: removed, config files remain. The folder /etc/php/8.3/fpm/ can therefore exist while the service does not. The opposite case also happens. The package is installed, but someone masked the unit, which links it to /dev/null so systemd refuses to start it.
Step-by-step
-
List the PHP versions that have files on disk.
ls /etc/php/Example output:
8.1 8.3Each number is a version that has, or once had, configuration here. If
8.3is missing, PHP 8.3 was never installed, or was purged. If it is present, check whether it has anfpmfolder withls /etc/php/8.3/. A version with onlycliandmods-availablehas the command-line PHP but not the service. -
Check the package state for every FPM package.
dpkg -l 'php*-fpm'Example output:
Desired=Unknown/Install/Remove/Purge/Hold | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) ||/ Name Version Architecture Description +++-==============-====================-============-================================================================= rc php8.1-fpm 8.1.2-1ubuntu2.19 amd64 server-side, HTML-embedded scripting language (FPM-CGI binary)iimeans installed.rcmeans removed with the configuration left behind. In this example the old 8.1 service is gone andphp8.3-fpmdoes not appear at all, so it was never installed or was purged. If the command printsdpkg-query: no packages found matching php*-fpm, no FPM package is installed or left behind in staterc. -
Ask systemd which FPM units it knows.
systemctl list-unit-files 'php*-fpm*'Example output:
UNIT FILE STATE PRESET php8.3-fpm.service masked enabled 1 unit files listed.0 unit files listed.confirms the package is missing.maskedmeans a mask is blocking the unit, and a restart then answersUnit php8.3-fpm.service is masked.instead; step 6 removes it.enabledordisabledmeans the unit exists under that exact name, so check the version number in the command you typed. -
Check where
php8.3-fpmwould come from.apt-cache policy php8.3-fpmExample output on Ubuntu 24.04, without the PPA:
php8.3-fpm: Installed: (none) Candidate: 8.3.6-0ubuntu0.24.04.13 Version table: 8.3.6-0ubuntu0.24.04.13 500 500 http://archive.ubuntu.com/ubuntu noble-updates/universe amd64 Packages 500 http://security.ubuntu.com/ubuntu noble-security/universe amd64 PackagesCandidate:must show a version. If the command prints nothing about the package, no configured source offers PHP 8.3. On Ubuntu 22.04 or Debian 12 that means you need the PPA or sury.org first, which the install guide covers. If a line underVersion table:namesppa.launchpadcontent.net/ondrej/phporpackages.sury.org, that version comes from the third-party source. -
Build the extension list from the old version, then install. Ask dpkg which extension packages the old version had. Packages in state
rcstill appear, which is what you want:dpkg -l 'php8.1-*' | awk '/^(ii|rc)/ {print $2}'Example output:
php8.1-cli php8.1-common php8.1-curl php8.1-fpm php8.1-gd php8.1-imagick php8.1-intl php8.1-mbstring php8.1-mysql php8.1-opcache php8.1-readline php8.1-xml php8.1-zipSome extensions from the Ubuntu or Debian archive may be installed under an unversioned name, such as
php-redisorphp-imagick.dpkg -l 'php-*'lists those, and you install thephp8.3-name of each. If the old PHP still runs,php8.1 -mlists the loaded modules as a second check. Install the same names for 8.3:sudo apt update sudo apt install php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd php8.3-imagick php8.3-intl php8.3-mbstring php8.3-xml php8.3-zipphp8.3-cli,php8.3-commonandphp8.3-opcachecome in as dependencies ofphp8.3-fpm. If apt answersE: Unable to locate packagefor one name, remove that name, finish the install, and look it up withapt-cache policyafterwards. Install the versioned package, notphp-fpm, so you get exactly 8.3. -
Unmask and start the service. A mask can survive a removal, because it lives in
/etc/systemd/system/, not in the package:sudo systemctl unmask php8.3-fpm sudo systemctl enable --now php8.3-fpm systemctl is-active php8.3-fpmExpected:
active. If the first command prints aRemovedline for/etc/systemd/system/php8.3-fpm.service, the unit was masked. If it prints nothing, it was not. Theenablecommand may also print a few lines about the SysV init script, which is normal.failedmeans the service starts and stops; go to the first troubleshooting item. -
Move custom pool settings across. Pools are the groups of PHP workers, one config file each. List both folders:
ls /etc/php/8.1/fpm/pool.d/ /etc/php/8.3/fpm/pool.d/If the old folder has only
www.conf, compare it with the new one withdiff /etc/php/8.1/fpm/pool.d/www.conf /etc/php/8.3/fpm/pool.d/www.conf. Copy across only the lines you changed, such aspm.max_children, never the whole file. Copy other pool files, such aserabliere.conf, withsudo cp. Then change any8.1in theirlisten =line to8.3:grep -n 'listen =' /etc/php/8.3/fpm/pool.d/*.conf sudo php-fpm8.3 -tExpected: one distinct
listen =path per pool, then a line ending inNOTICE: configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful. Restart withsudo systemctl restart php8.3-fpmonce the test passes. -
Point the web server at the new socket. Find every reference to the old one:
sudo grep -rn 'php8.1-fpm' /etc/nginx/ /etc/apache2/ 2>/dev/nullOn nginx, an old line looks like
fastcgi_pass unix:/run/php/php8.1-fpm.sock;. The error log showsconnect() to unix:/run/php/php8.1-fpm.sock failed (2: No such file or directory) while connecting to upstream, and visitors get a 502. Edit each file the grep found, changephp8.1-fpm.socktophp8.3-fpm.sock, then test and reload:sudo nginx -t && sudo systemctl reload nginxExpected:
nginx: the configuration file /etc/nginx/nginx.conf syntax is okandnginx: configuration file /etc/nginx/nginx.conf test is successful.On Apache, the package ships
/etc/apache2/conf-available/php8.3-fpm.confbut does not enable it. Switch the configuration over:sudo a2enmod proxy_fcgi setenvif sudo a2disconf php8.1-fpm sudo a2enconf php8.3-fpm sudo apachectl configtest && sudo systemctl reload apache2Expected:
Syntax OK.a2disconfmay report thatphp8.1-fpmdoes not exist, which is fine. Fix anySetHandler "proxy:unix:/run/php/php8.1-fpm.sock|fcgi://localhost"line the grep found in a virtual host. Ifa2query -mlistsphp8.1, the old mod_php module (PHP running inside Apache) is still on, so runsudo a2dismod php8.1.
Validate it works
-
The unit runs and the socket exists.
systemctl is-active php8.3-fpm ls -l /run/php/Expected:
active, and a line forphp8.3-fpm.sockowned bywww-data. -
A WordPress page answers.
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/ curl -s -o /dev/null -w '%{http_code}\n' https://example.com/wp-login.phpExpected:
200for both.502on nginx or503on Apache means the web server still reaches for a socket that is not there, so repeat step 8. -
PHP-FPM serves 8.3, not something else.
wp --inforeports the command-line PHP, not the one behind the site. Ask the web server directly with a temporary file, then delete it. Replace/var/www/example.comwith your document root, therootline in nginx orDocumentRootin Apache:echo '<?php echo PHP_VERSION, " ", PHP_SAPI;' | sudo tee /var/www/example.com/fpm-check-7f3a.php >/dev/null curl -s https://example.com/fpm-check-7f3a.php; echo sudo rm /var/www/example.com/fpm-check-7f3a.phpExample output:
8.3.6 fpm-fcgifpm-fcgiconfirms the request went through PHP-FPM. A403or404means your configuration only runs WordPress’s own PHP files, which is a good rule to keep. If you have the FPM status page turned on, it also shows the pool name, and the status page guide explains its fields. -
WordPress has its extensions. Log in to WordPress and open Tools » Site Health. No critical issue should name a missing PHP module.
Troubleshooting
-
The unit starts, then fails. Read the reason:
journalctl -u php8.3-fpm -n 30 --no-pager sudo php-fpm8.3 -tA copied pool usually causes it.
ERROR: [/etc/php/8.3/fpm/pool.d/erabliere.conf:23] unknown entry 'pm.max_requets'names the file, the line and the misspelled setting.ERROR: [pool erabliere] cannot get uid for user 'erabliere'means the pool’suser =account does not exist on this server. -
Two pools share one socket. Within PHP 8.3,
php-fpm8.3 -treports[pool erabliere] unable to set listen address as it's already used in another pool 'www'. Give each pool its ownlisten =path. If an old PHP version still runs on the same path, the journal showsAnother FPM instance seems to already listen on /run/php/php8.3-fpm.sock. Stop the old service withsudo systemctl disable --now php8.1-fpm. -
apt refuses because of mixed sources. A message such as
php8.3-fpm : Depends: php8.3-common (= 8.3.6-0ubuntu0.24.04.13) but 8.3.14-1+ubuntu24.04.1+deb.sury.org+1 is to be installedmeans some PHP packages come from Ubuntu and others from the PPA. Runapt-cache policy php8.3-common php8.3-fpmto see each origin. Choose one source and install everyphp8.3-*package from it. -
The config folder is gone, but dpkg says
rc. If someone deleted/etc/php/8.3/by hand, a normal reinstall does not bring the files back. dpkg skips configuration files you removed on purpose. Ask it to restore them:sudo apt install --reinstall -o Dpkg::Options::="--force-confmiss" php8.3-fpm -
The site works, but WP-CLI or cron shows another version.
php -vreports the command-line PHP that/usr/bin/phppoints to, which is separate from FPM. Runsudo update-alternatives --config phpand pick/usr/bin/php8.3. Cron jobs that callphpfollow the same choice.
For 502 causes that remain once the socket is right, such as timeouts or a pool out of workers, see fixing an nginx 502 Bad Gateway.
When this is the wrong approach
On a cPanel & WHM server, PHP comes from EasyApache 4 as ea-phpXY packages, with services named ea-php83-php-fpm. Do not install php8.3-fpm with apt there, because it bypasses cPanel and can collide with its packages. Follow the cPanel apache_php_fpm guide instead.
In a Docker container, there is usually no systemd, so systemctl cannot find any unit. PHP-FPM runs as the container’s main process, and you change versions by changing the image, for example php:8.3-fpm. The same applies to managed platforms that pick the PHP version for you.
If the release upgrade also changed nginx, Apache or MySQL, fix PHP first, then check those services one at a time. The Debian manual page for systemctl describes mask, unmask and list-unit-files in full.
Running WordPress that earns real money deserves an operator — Stack Harbor runs that stack under Enterprise WordPress; book an infrastructure consult.