Troubleshooting: loading carthage framework error: dyld: Library not loaded: @rpath/...

Troubleshooting: loading carthage framework error: dyld: Library not loaded: @rpath. How to locate which carthage framework missing dependence?

Last Update: September 19, 2023

Symptom

iOS project use carthage frameworks, compile successfully. However crash at run time with “Library not loaded” error. For example:

dyld: Library not loaded: libswiftXCTest.dylib
  Referenced from: ~/Library/Developer/CoreSimulator/Devices/E1234678-0F37-4991-B362-224440471FD7/data/Containers/Bundle/Application/55B7875B-11CB-4BE8-AA4F-38BACCC586B6/FooApp.app/FooApp
  Reason: image not found
dyld: launch, loading dependent libraries

Analyze of `dyld: Library not loaded...` error

The error tells a framework can not not be loaded. In this example, the libswiftXCTest.dylib can not be found in app. There must some framework depends on libswiftXCTest.dylib. The question is how to find which framework depends on libswiftXCTest.dylib?

Luckly, there is otool (object file displaying tool) for inspecting Mach-O binaries, otool can be used to find framework dependencies. with -L parameter:

-L   Display the names and version numbers of the shared libraries that the object file uses,
     as well as the shared library ID if the file is a shared library.

Example of otool -L usage, with input and output:

$ otool -L Carthage/Build/iOS/RxTest.framework/RxTest

Carthage/Build/iOS/RxTest.framework/RxTest:
	@rpath/RxTest.framework/RxTest (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/swift/libswiftXCTest.dylib (compatibility version 1.0.0, current version 0.0.0, weak)
	/System/Library/Frameworks/Foundation.framework/Foundation (compatibility version 300.0.0, current version 1770.255.0)
	/usr/lib/libobjc.A.dylib (compatibility version 1.0.0, current version 228.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1292.60.1)
	@rpath/RxSwift.framework/RxSwift (compatibility version 1.0.0, current version 1.0.0)
	@rpath/libswiftCore.dylib (compatibility version 1.0.0, current version 1200.2.41)
	@rpath/libswiftCoreFoundation.dylib (compatibility version 1.0.0, current version 1.6.0, weak)
	@rpath/libswiftCoreGraphics.dylib (compatibility version 1.0.0, current version 2.0.0, weak)
	@rpath/libswiftCoreImage.dylib (compatibility version 1.0.0, current version 1.0.0, weak)
	@rpath/libswiftDarwin.dylib (compatibility version 1.0.0, current version 0.0.0, weak)
	@rpath/libswiftDispatch.dylib (compatibility version 1.0.0, current version 4.40.2, weak)
	@rpath/libswiftFoundation.dylib (compatibility version 1.0.0, current version 20.0.0)
	@rpath/libswiftMetal.dylib (compatibility version 1.0.0, current version 1.3.1, weak)
	@rpath/libswiftObjectiveC.dylib (compatibility version 1.0.0, current version 1.0.0, weak)
	@rpath/libswiftQuartzCore.dylib (compatibility version 1.0.0, current version 1.0.0, weak)
	@rpath/libswiftUIKit.dylib (compatibility version 1.0.0, current version 19.0.0, weak)

With otool, we can find all the carthage frameworks with following command:

otool -L Carthage/Build/iOS/*.framework/* > dependencies.txt

The above command write all the carthage frameworks dependencies into dependencies.txt.

Inside dependencies.txt, you can find which framework depends on missing framework.

otool quick reference

USAGE

  llvm-otool [option…] [file…]

DESCRIPTION

  otool is a tool for dumping Mach-O files.

OPTIONS:

  -arch <value>	Select slice of universal Mach-O file.
  -C    Print linker optimization hints.
  -D    Print shared library id.
  -d    Print data section.
  -f    Print universal headers.
  -G    Print data-in-code table.
  -h    Print mach header.
  -I    Print indirect symbol table.
  -j    Print opcode bytes.
  -L    Print used shared libraries.
  -l    Print load commands.
  -mcpu=<value>	Select cpu for disassembly.
  -o    Print Objective-C segment.
  -P    Print __TEXT,__info_plist section as strings.
  -p <function name>	Start disassembly at <function name>.
  -r    Print relocation entries.
  -s <segname> <sectname>		Print contents of section.
  -t    Print text section.
  -V    Symbolize disassembled operands (implies -v).
  -v    Verbose output / disassemble when printing text sections.
  -X    Omit leading addresses or headers.
  -x    Print all text sections.
  @<FILE>    Read command-line options and commands from response file <FILE>.

  --version  Print version.