Troubleshooting shared library errors

When an application fails with a shared library error, this generally implies that:

• A key component of either Mac® OS X or the affected application is missing or corrupted.
• A key component or dependency of the affected application is incompatible with the installed version of Mac OS X.

That key component is a shared library. This FAQ addresses the following topics concerning troubleshooting shared library errors:

• About shared libraries.
• Causes of shared library errors.
• Resolving shared library errors.
• Preventing shared library errors.

About shared libraries

Shared libraries are collections of programming and data that can be used by multiple applications. They can permit applications to use memory efficiently by sharing common programming and resources, as well as simplify application development. For example, a developer writing an application that works with QuickTime® files can use functions provided by QuickTime's shared libraries. For readers familiar with Microsoft® Windows®, Mac OS X shared libraries are analogous to Windows dynamic link libraries (.dll).

Shared libraries are either static or dynamic. More precisely, they are either statically linked or dynamically linked. For the purposes of this FAQ, the primary differences between static and dynamic shared libraries are that an application employing dynamic shared libraries can be smaller, load faster, and use less RAM than if that application was coded using static shared libraries. [1]

Shared libraries are distributed in frameworks, as standalone dynamic shared libraries, and as import libraries. [2]

Mac OS X includes a vast number of shared libraries, which are used by both applications and the operating system itself. Applications can use Mac OS X's shared libraries, their own shared libraries, or a combination thereof.

Causes of shared library errors

Common causes of shared library errors include:

• Problems with your Mac OS X startup disk.
• Corrupted Mac OS X installation.
• The affected application is:
  • Corrupted.
  • Incompatible with the version of Mac OS X you are using.
  • Dependent upon another application or operating system component which is either:
    • Corrupted.
    • Incompatible with the affected application or the installed version of Mac OS X.

Resolving shared library errors

As shared libraries are often fundamental components of the operating system, resolving a shared library error often requires reinstalling Mac OS X. Nevertheless, under certain circumstances, it may be possible to resolve a shared library error without reinstalling the operating system. Perform the following steps in the order specified:

1. Assure your startup disk is in proper order by performing Steps 1-3 of the Procedure specified in our "Resolving Disk, Permission, and Cache Corruption" FAQ.
2. If the problem persists and the shared library error arose shortly after installing a Mac OS X Update, then downloading and reapplying the Mac OS X Combo Update corresponding to the version of Mac OS X you are using may resolve the problem.
   1. Note:
      1. We have not tested this approach: it is suggested based solely upon a number of reports we have read. [3]
      2. Step 1 must be performed prior to attempting this step, otherwise one risks data loss due to the installation of the Combo Update on a startup disk with a corrupted directory.
      3. Prior to reapplying the Combo Update, we recommend you make a new backup of the startup disk in question using your comprehensive backup and recovery solution.
      4. If reapplying the Combo Update fails during installation, reinstall Mac OS X.
3. If the problem persists, and you have just installed the affected application, assure that the version of Mac OS X you are using is compatible with the system requirements of the affected application. The system requirements for an application can usually be determined by consulting its documentation, the developer's Web site, or by contacting the developer.
4. If the problem persists and only one application is affected, uninstall, then reinstall the affected application. See our "Uninstalling applications" FAQ for important advice on uninstalling software.
5. If the problem persists, examine the shared library error message for clues that may indicate that the problem is due to another application upon which the affected application depends.
   1. A shared library error message may appear in either an alert dialog or Console logs. The error message is usually in the following format:
   2. The application "app" could not be launched because of a shared library error:"<<app><srting1><string2><>"
   3. where app is the name of the affected application and string1 and string2 pertain to the shared library in question.
   4. If string1 or string2 contain text that corresponds to another application's name, then the affected application may depend upon a shared library provided by that other application.
   5. For example, the shared library error message:
   6. The application "app" could not be launched because of a shared library error:"<<app><Apple;Carbon;Multimedia><CFMPriv_QuickTime><>"
   7. could imply that the installed version of QuickTime may either be corrupted or incompatible with the application app due to the presence of the text CFMPriv_QuickTime in the message. In this case, installing either the latest version of QuickTime, or a specific version of QuickTime required by the affected application, may solve the problem. [4]
   8. If an examination of the shared library error message indicates that the affected application is dependent upon another application:
      1. Assure you are running the correct, compatible version of the other application cited in the shared library error message.
      2. Reinstall the other application cited in the shared library error message.
6. If all else fails, reinstall Mac OS X:
   1. If you are running Mac OS X 10.6, see the AppleCare Knowledge Base document "Mac OS X 10.6 Help: Reinstalling Mac OS X."
   2. If you are running Mac OS X 10.5 or earlier, use the Archive and Install process. See our "General advice on performing an Archive and Install" FAQ.

Preventing shared library errors

• Perform the regular maintenance recommended in our "Maintaining Mac OS X" FAQ. In particular, perform a periodic check of your hard drives for problems.
• Implement the advice in the "Protecting Against Power Problems" chapter of our book Troubleshooting Mac OS X.
• Before installing Mac OS X Updates, follow the advice in our "Installing Software Updates" FAQ.
• Before installing applications or application updates, assure they are compatible with the version of Mac OS X you are using by reviewing the application's documentation, checking the developer's Web site, or contacting the developer.

Related links

• Shared library concepts
  • Library (computing). From Wikipedia®, the free encyclopedia.
  • Seebach, P. "Dissecting shared libraries" IBM® developerWorks®. 11 January 2005.
• AppleCare® Knowledge Base documents
  • "Power Macintosh: Run Time Environment."
• Apple® Developer Connection documents
  • Carbon Overview.
  • Code Fragment Manager Reference.
  • Dynamic Library Programming Topics.
  • Framework Programming Guide.
  • Mac OS X ABI Mach-O File Format Reference.
  • Mac OS X Technology Overview.
  • Mach-O Programming Topics.

Notes

[1] Whether a developer codes their application using static or dynamic shared libraries is a question beyond the scope of this FAQ: each approach has both advantages and disadvantages. For additional information on static vs. dynamic shared libraries, consult the references cited in the "Shared library concepts" subsection of the Related links section of this FAQ.

[2] The following notes describe frameworks, standalone dynamic shared libraries, and import libraries:

• Frameworks are the preferred method of distributing shared code and related resources in Mac OS X. The shared code within a framework is bundled in a dynamically-linked shared library or a dynamic shared library for short.
• Standalone dynamic shared libraries are used to distribute shared code independent of a framework.
• Import libraries are a legacy (pre-Mac OS X) method of distributing shared programming and related data in code fragments. Code fragments are distributed in Preferred Executable Format (PEF) binaries, the native executable file format for Classic applications on PowerPC™-based Macs. Code Fragment Manager (CFM) loads code fragments into memory. The Carbon application environment supports CFM. However, the native Mac OS X executable file format is Mach-O (Mach Object). To enable CFM to use Mach-O system libraries, Mac OS X includes bridging code in the form of CFMPriv_* libraries.

[3] Examples of such reports can be found by searching the Web or the Apple Discussions.

[4] As discussed in Note [2], the CFMPriv_* libraries are bridging code enabling Code Fragment Manager (CFM) to use Mach-O executables, the latter being the native executable file format on Mac OS X. If the Mach-O executable in question, i.e. the text following the underscore in CFMPriv_, is a component of the operating system, then reinstalling Mac OS X will probably be required to correct the shared library error.