errno 87 (ESHLIBVERS): meaning and diagnosis

Status / error code:		Category:

Constant name:
Source:		Operating System:
Description: a dependent shared library failed the Mach-O compatibility-version check.

Could be also:
Constant	Type	OS
ERROR_INVALID_PARAMETER	Win32 error	Windows
EUSERS	errno	Linux
ELIBEXEC	errno	Solaris
XNS_INTERNAL_ERROR	BugCheck Code	Windows

Previous	Next
EBADARCH	EBADMACHO

ESHLIBVERS

ESHLIBVERS is the Darwin program-loading result for a shared-library version mismatch. It is not simply “a library is missing.” Apple’s dynamic-library documentation describes a compatibility check for dependent libraries: before loading one, dyld compares the library’s current version on disk with the compatibility version recorded when the client was linked. If the current version is older than the required compatibility version, the dependent library is not loaded.

This is an ABI compatibility problem. A library can have the expected pathname and a compatible CPU architecture but still be too old for the client binary. Conversely, changing a filename or copying an arbitrary newer-looking .dylib does not prove that the library exposes the ABI the client needs.

Evidence to collect

Run otool -L <client> and otool -L <library>; Apple documents this command for viewing current and compatibility versions.
Use otool -l when the install name or load commands must be compared. The Mach-O format uses LC_LOAD_DYLIB in clients and LC_ID_DYLIB in dynamic libraries.
Record the exact client, the resolved library path, and both version values. These facts distinguish a version failure from a missing file, malformed Mach-O image, or wrong architecture.

Correct resolution

Deploy the library revision whose declared compatibility version meets the client’s requirement, or rebuild the client and library as a compatible set. Apple’s library design guidance recommends a distinct install name for an incompatible major revision, rather than allowing clients to bind accidentally to a library with a changed ABI.

The documented version comparison applies to dependent libraries. A library opened directly with dlopen follows a different path; capture dlerror() for that call rather than assuming that every dynamic-loading message is an ESHLIBVERS case.

References

Looking for a different code? Search another status or error code.