Troubleshooting PHP 8.3 mbstring issues on Ubuntu with Nginx

Maintaining a Drupal site is usually smooth sailing once the environment is properly set up. However, even in a stable environment, updates to modules can sometimes reveal underlying configuration issues that weren't apparent before. This was the case when I updated a contrib module on a Drupal 10.3 site, which suddenly started throwing errors related to the mbstring PHP extension.

The problem

The problem first surfaced after updating the search_api_attachments contrib module. The Drupal site, which had been running smoothly on PHP 8.3 and Ubuntu with Nginx, started displaying the following error:

Error: Call to undefined function mb_strcut() in Drupal\search_api_attachments\Plugin\search_api\processor\FilesExtractor->limitBytes() (line 415 of modules/contrib/search_api_attachments/src/Plugin/search_api/processor/FilesExtractor.php).

This error indicated that the mbstring PHP extension, required by the updated module, was not functioning properly.

I checked whether mbstring was installed with the following command:

php -m | grep mbstring

Instead of finding the extension listed, I received the following warning:

PHP Warning:  PHP Startup: Unable to load dynamic library 'mbstring' (tried: /usr/lib/php/20230831/mbstring (/usr/lib/php/20230831/mbstring: cannot open shared object file: No such file or directory), /usr/lib/php/20230831/mbstring.so (/usr/lib/php/20230831/mbstring.so: cannot open shared object file: No such file or directory)) in Unknown on line 0

This error indicated that the mbstring extension was missing or not correctly installed, even though PHP was trying to load it.

Diagnosing the issue

The next step was to attempt reinstalling the mbstring extension:

sudo apt-get install --reinstall php8.3-mbstring

However, this command returned a dependency error:

The following packages have unmet dependencies:
php8.3-mbstring : Depends: php8.3-common (= 8.3.6-0ubuntu0.24.04.1) but 8.3.7-1+ubuntu20.04.1+deb.sury.org+1 is to be installed
E: Unable to correct problems, you have held broken packages.

The problem was clear: a version mismatch between php8.3-mbstring and php8.3-common, both of which are necessary for the extension to function correctly.

Resolving the issue

After identifying the root cause, I took the following steps to resolve the issue.

1. Verify the mbstring Extension

First, I checked whether the mbstring extension was loaded by running:

php -m | grep mbstring

The extension was not listed, confirming that it wasn't loaded properly.

2. Attempt to Reinstall mbstring

To fix the issue, I tried reinstalling the mbstring extension:

sudo apt-get install --reinstall php8.3-mbstring

However, this didn't resolve the problem, so I moved on to further investigation.

3. Check installed PHP packages

I checked the installed PHP packages and confirmed they were all sourced from the deb.sury.org PPA, which is a popular repository for PHP on Ubuntu:

sudo apt list --installed | grep php8.3

The output showed that all PHP 8.3 packages were indeed from the deb.sury.org repository, but the version mismatch indicated a potential problem with how they were installed.

4. Add the deb.sury.org repository

To ensure that all PHP packages were consistently sourced, I re-added the deb.sury.org repository:

sudo add-apt-repository ppa:ondrej/php
sudo apt-get update

5. Purge and reinstall mbstring

Next, I purged the problematic mbstring package to start fresh

sudo apt-get purge php8.3-mbstring

After purging, I reinstalled the mbstring extension:

sudo apt-get install php8.3-mbstring

6. Verify installation and restart Nginx

After reinstalling, I checked again to see if the mbstring extension was loaded correctly:

php -m | grep mbstring

This time, the extension was listed correctly. I then restarted Nginx to apply the changes:

sudo service nginx restart

7. Check for Held Packages and Upgrade

To ensure everything was up to date and there were no held packages causing issues, I ran:

sudo apt-mark showhold
sudo apt-get upgrade

With these steps, the mbstring extension was correctly loaded, and my Drupal site began functioning properly without the previous errors.

The wrap

Consistency is key: Ensure that all PHP packages are sourced from the same repository to avoid version conflicts.

Diagnose before acting: Understanding the root cause of the issue (in this case, a version mismatch) helps in applying the right solution.

Be prepared for manual fixes: Sometimes, automated package management doesn’t resolve the issue, so manual intervention might be necessary.

I hope this article helps others facing similar issues with PHP extensions on Ubuntu. Troubleshooting can be frustrating, but with patience and the right approach, most problems can be resolved efficiently.