firebase / firebase/firebase-ios-sdk
macOS: linker crash "unsupported reference (alias of) to class-ref" (ClassRefToGotConverter) linking FirebaseCore + FirebaseFirestore frameworks on Xcode 27
- Dominant language
- C++
- Stars
- 6.7k
- Forks
- 1.8k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 75
Description
### Environment
- Firebase C++ SDK: 13.12.0 (its macOS `frameworks/darwin` distribution wraps the underlying Firebase Apple SDK; "macOS SDKs are now built using Xcode 26.2" per the C++ SDK release notes starting around 13.8.0)
- Xcode: 27.0 (27A266a)
- clang: Apple clang version 21.0.0 (clang-2100.3.34.2)
- ld: version 27037.1 (new/default linker)
- macOS: 26.6.2 (build 25G83)
- Architecture: arm64 (Apple Silicon)
- `MACOSX_DEPLOYMENT_TARGET`: 15.7
- Frameworks linked: `firebase.framework`, `firebase_firestore.framework`, `firebase_auth.framework`, `firebase_analytics.framework`, `firebase_functions.framework`, `firebase_messaging.framework`, `firebase_remote_config.framework` (the macOS desktop frameworks bundled by the Firebase C++ SDK, which wrap the Apple SDK)
### What happens
Linking a macOS desktop app against `firebase.framework` + `firebase_firestore.framework` fails with a linker crash (not a normal "undefined symbol" error — the linker itself asserts and aborts):
```
ld: unsupported reference (alias of) to class-ref from '_f_b_OBJC_CLASSLIST_REFERENCES_$_' (firebase_firestore.framework/firebase_firestore[arm64][1145](9c7b11ffbad0c92d0adcf47d138d4f4c_error_apple.mm.o))
ld: unsupported reference (alias of) to class-ref from '_OBJC_CLASSLIST_REFERENCES_$_' (firebase.framework/firebase[arm64][181](2821dc7f0f996caf95294ccbe3bb0f98_locale_apple.mm.o))
0 0x10222f670 __assert_rtn + 252
1 0x1021813f0 ___ZN2ld4pass22ClassRefToGotConverter9transformEv_block_invoke_2 + 0
2 0x1825254c8 _dispatch_client_callout2 + 16
3 0x1825201a4 _dispatch_apply_invoke3 + 336
4 0x1825254b0 _dispatch_client_callout + 16
5 0x18250e630 _dispatch_once_callout + 32
6 0x18251f2f4 _dispatch_apply_invoke + 248
7 0x1825254b0 _dispatch_client_callout + 16
8 0x182542d6c _dispatch_channel_invoke.cold.9 + 28
9 0x18251dadc _dispatch_root_queue_drain + 708
10 0x18251e120 _dispatch_worker_thread2 + 184
11 0x1826c3e84 _pthread_wqthread + 232
ld: Assertion failed: (0 && "unsupported references to class-ref"), function changeClassRefUseToGotUse, file ObjC.cpp, line 1151.
clang++: error: linker command failed with exit code 1 (use -v to see invocation)
```
It appears an Objective-C class reference is aliased across **two separate framework binaries** — one class-ref inside `firebase_firestore.framework`'s `error_apple.mm.o` and one inside `firebase.framework`'s `locale_apple.mm.o` — and the linker's new `ClassRefToGotConverter` pass hard-asserts instead of handling it.
### What we've tried
1. **`-ld_classic`** — no longer has any effect on Xcode 27: `ld: warning: -ld_classic is no longer supported and will be ignored`. Same crash occurs anyway.
2. **No special linker flags at all** — same crash. This confirms it's not specific to `-ld_classic`; the default linker crashes on its own.
3. **`-Xlinker -dead_strip -Xlinker -allow_dead_duplicates`** (suggested as a workaround for a related issue in #15284) — this does avoid the crash, but as a side effect the linker silently discards unrelated, legitimate symbols from other static libraries linked into the same binary (we saw `Undefined symbol` errors reappear afterward for FreeType, ICU, and other unrelated libraries), so it's not a safe workaround.
### Expected behavior
The prebuilt macOS frameworks should link without crashing the linker, ideally without requiring `-allow_dead_duplicates` (which has known correctness risks per Apple's own linker docs).
### Related issue
This looks closely related to #15284 (FirebaseAnalytics + `-ld_classic` on iOS), but reproduces here on macOS desktop with the default (non-classic) linker, so it isn't limited to `-ld_classic` usage.
### Question for the Firebase team
Is this a duplicate/aliased symbol artifact from how `firebase.framework` and `firebase_firestore.framework` are packaged for macOS (e.g., the same translation unit/class getting folded into an alias across two separate framework binaries)? Has this been reproduced internally on Xcode 27, and is there a recommended workaround in the meantime (e.g. pinning to an older SDK release built with an earlier Xcode)?
Contributor guide
Research direction
Start by reproducing the link with firebase.framework and firebase_firestore.framework on the stated Xcode 27 environment, then inspect the ClassRefToGotConverter failure involving error_apple.mm.o and locale_apple.mm.o. Compare the tested linker flags and SDK versions described in the issue. Done means identifying a safe fix or documented workaround that links the prebuilt macOS frameworks without the reported crash or unrelated missing symbols.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, macos, objective-c
- Domain
- build-system, databases, desktop-dev
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100