Skip to content

Fix "Unit php8.3-fpm.service not found" on Ubuntu

When systemctl answers that php8.3-fpm.service is not found, you can find which PHP-FPM versions are really installed, reinstall the service with the extensions your WordPress site used, and point nginx or Apache at the new socket. You finish with the unit running and pages served by the PHP version you expect.

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-fpm with 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 200 and is served by PHP 8.3 through PHP-FPM.

Prerequisites

  • Root or sudo access 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-upgrade from 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.

Decision path for Unit php8.3-fpm.service not found: first check that /etc/php/8.3/fpm exists, then that dpkg shows php8.3-fpm as ii rather than rc, then that the unit is not masked, and finally that nginx or Apache points at /run/php/php8.3-fpm.sock instead of the old php8.1 socket, which is the usual failure behind a 502 after the service is fixed

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

  1. List the PHP versions that have files on disk.

    ls /etc/php/

    Example output:

    8.1  8.3

    Each number is a version that has, or once had, configuration here. If 8.3 is missing, PHP 8.3 was never installed, or was purged. If it is present, check whether it has an fpm folder with ls /etc/php/8.3/. A version with only cli and mods-available has the command-line PHP but not the service.

  2. 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)

    ii means installed. rc means removed with the configuration left behind. In this example the old 8.1 service is gone and php8.3-fpm does not appear at all, so it was never installed or was purged. If the command prints dpkg-query: no packages found matching php*-fpm, no FPM package is installed or left behind in state rc.

  3. 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. masked means a mask is blocking the unit, and a restart then answers Unit php8.3-fpm.service is masked. instead; step 6 removes it. enabled or disabled means the unit exists under that exact name, so check the version number in the command you typed.

  4. Check where php8.3-fpm would come from.

    apt-cache policy php8.3-fpm

    Example 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 Packages

    Candidate: 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 under Version table: names ppa.launchpadcontent.net/ondrej/php or packages.sury.org, that version comes from the third-party source.

  5. Build the extension list from the old version, then install. Ask dpkg which extension packages the old version had. Packages in state rc still 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-zip

    Some extensions from the Ubuntu or Debian archive may be installed under an unversioned name, such as php-redis or php-imagick. dpkg -l 'php-*' lists those, and you install the php8.3- name of each. If the old PHP still runs, php8.1 -m lists 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-zip

    php8.3-cli, php8.3-common and php8.3-opcache come in as dependencies of php8.3-fpm. If apt answers E: Unable to locate package for one name, remove that name, finish the install, and look it up with apt-cache policy afterwards. Install the versioned package, not php-fpm, so you get exactly 8.3.

  6. 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-fpm

    Expected: active. If the first command prints a Removed line for /etc/systemd/system/php8.3-fpm.service, the unit was masked. If it prints nothing, it was not. The enable command may also print a few lines about the SysV init script, which is normal. failed means the service starts and stops; go to the first troubleshooting item.

  7. 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 with diff /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 as pm.max_children, never the whole file. Copy other pool files, such as erabliere.conf, with sudo cp. Then change any 8.1 in their listen = line to 8.3:

    grep -n 'listen =' /etc/php/8.3/fpm/pool.d/*.conf
    sudo php-fpm8.3 -t

    Expected: one distinct listen = path per pool, then a line ending in NOTICE: configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful. Restart with sudo systemctl restart php8.3-fpm once the test passes.

  8. 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/null

    On nginx, an old line looks like fastcgi_pass unix:/run/php/php8.1-fpm.sock;. The error log shows connect() 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, change php8.1-fpm.sock to php8.3-fpm.sock, then test and reload:

    sudo nginx -t && sudo systemctl reload nginx

    Expected: nginx: the configuration file /etc/nginx/nginx.conf syntax is ok and nginx: configuration file /etc/nginx/nginx.conf test is successful.

    On Apache, the package ships /etc/apache2/conf-available/php8.3-fpm.conf but 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 apache2

    Expected: Syntax OK. a2disconf may report that php8.1-fpm does not exist, which is fine. Fix any SetHandler "proxy:unix:/run/php/php8.1-fpm.sock|fcgi://localhost" line the grep found in a virtual host. If a2query -m lists php8.1, the old mod_php module (PHP running inside Apache) is still on, so run sudo a2dismod php8.1.

Validate it works

  1. The unit runs and the socket exists.

    systemctl is-active php8.3-fpm
    ls -l /run/php/

    Expected: active, and a line for php8.3-fpm.sock owned by www-data.

  2. 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.php

    Expected: 200 for both. 502 on nginx or 503 on Apache means the web server still reaches for a socket that is not there, so repeat step 8.

  3. PHP-FPM serves 8.3, not something else. wp --info reports 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.com with your document root, the root line in nginx or DocumentRoot in 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.php

    Example output:

    8.3.6 fpm-fcgi

    fpm-fcgi confirms the request went through PHP-FPM. A 403 or 404 means 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.

  4. 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 -t

    A 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’s user = account does not exist on this server.

  • Two pools share one socket. Within PHP 8.3, php-fpm8.3 -t reports [pool erabliere] unable to set listen address as it's already used in another pool 'www'. Give each pool its own listen = path. If an old PHP version still runs on the same path, the journal shows Another FPM instance seems to already listen on /run/php/php8.3-fpm.sock. Stop the old service with sudo 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 installed means some PHP packages come from Ubuntu and others from the PPA. Run apt-cache policy php8.3-common php8.3-fpm to see each origin. Choose one source and install every php8.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 -v reports the command-line PHP that /usr/bin/php points to, which is separate from FPM. Run sudo update-alternatives --config php and pick /usr/bin/php8.3. Cron jobs that call php follow 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.