configure: error: utf8_mime2text() has new signature, but U8T_CANONICAL is missing

configure: error: utf8_mime2text() has new signature, but U8T_CANONICAL is missing

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Resolving the utf8_mime2text() Signature Mismatch in PHP Builds

The error configure: error: utf8_mime2text() has new signature, but U8T_CANONICAL is missing indicates a fundamental mismatch between the version of the ICU (International Components for Unicode) library your build system expects and the actual library installed on your target machine. This specific failure often surfaces when upgrading PHP on macOS, particularly in environments like Mountain Lion where legacy system libraries were bundled with older expectations.

When you run the ./configure command, PHP's build script attempts to link against the ICU library for internationalization support (enabled via --enable-intl). The error message is cryptic because it describes a C-level API contract violation: the header files (php_intl.h) declare the function utf8_mime2text() with a newer signature that accepts an U8T_CANONICAL argument, but the compiled library (.a or .so file) you are linking against was built using an older ICU version that does not define this constant.

This is rarely a logic error in your code; it is an environment configuration issue. The root cause is almost always that the --with-icu-dir=/usr flag in your command points to a system framework where the headers match one version of ICU, but the pre-compiled or compiled library binaries correspond to a different, older patch level.

Investigating the Build Log

The error message explicitly directs you to config.log. This file is the definitive source of truth for configure-time decisions. You must inspect the output of the ICU checks within that log. Look for lines indicating where the header files were found versus where the library was found.

In many macOS installations, especially older ones, you might find that /usr/include/icu/ contains headers from a recent update, while /usr/lib/libicui18n.dylib (or similar) remains an older binary. The configure script successfully includes the header, sees the new function signature, but fails when trying to link the object code against the old library which lacks the definition for U8T_CANONICAL.

Resolving via Manual ICU Installation

The most robust solution is to ensure that the headers and the libraries originate from the exact same build artifact. On macOS Mountain Lion, relying on the system /usr directory for mixed-version dependencies is risky.

If you have access to a newer version of Xcode or can install a compatible ICU framework manually, you should point your configure command to a consistent directory containing both the headers and the libraries. For example:

./configure \
--prefix=/usr \
--with-icu-dir=/opt/icu \
# ... other flags

However, before installing new frameworks, verify if a system update is available. On Mountain Lion, Apple occasionally updated the ICU bundle in later OS updates to resolve these header/library mismatches. If you are on an older release of Mountain Lion without the latest patch, upgrading the OS itself may align the system libraries.

The --without-intl Workaround

If upgrading the environment is not feasible, and you do not strictly require the intl extension for your application, you can disable it during the build process. This removes the dependency on the problematic ICU components entirely.

Add or modify the --enable-intl flag to --without-intl in your configure command:

./configure \
# ... other flags
--without-intl \
# ... other flags

This forces PHP to skip the compilation of the internationalization extension. While this eliminates the specific error, it means you lose date/time formatting functions like IntlDateFormatter and currency formatting capabilities. This is a trade-off: stability vs. functionality. For many legacy systems running on Mountain Lion, sacrificing intl was an acceptable compromise to get PHP 5.x or early 7.x up and running without modifying the underlying OS libraries.

Why This Happens with Custom Builds

The long configure command you provided includes numerous flags like --with-mysql=mysqlnd and --with-openssl=/usr. When mixing system-provided libraries (like OpenSSL) with custom-installed ones, or relying on a mix of system headers and binaries, the risk of ABI incompatibility increases. The ICU case is particularly notorious because Unicode data handling evolves frequently; a header update often precedes a library update. If they are not synchronized, the linker fails to resolve the new symbols expected by the headers against the old binary definitions.

Always prioritize using a unified source for your dependencies when compiling PHP from source on macOS. Using Homebrew or MacPorts to manage these dependencies often resolves these inconsistencies automatically, as they provide consistent header/library pairings within their own prefixes.

Our network