Xcode 27.2: Mac Catalyst-Kompilierung fehlgeschlagen? Reparaturanleitung 2026

Apple führt in den Release Notes zu Xcode 27.2 Beta 2 einen Mac-Catalyst-Compilerfehler auf, wenn iOS-27.1-spezifische APIs verwendet werden (offizielle Release Notes). Das ist ein bekannter Fehler für den dort beschriebenen Versionsstand, aber keine Erklärung für jeden fehlgeschlagenen Catalyst-Build.

Symptom → schnellster Weg: Scheitert nur Mac Catalyst an einem iOS-27.1-Symbol, prüfen Sie zuerst die Plattformzugehörigkeit und isolieren Sie den betroffenen Quellcode per Kompilierbedingung. Bauen Sie anschließend denselben Commit getrennt für iOS und Mac Catalyst. Ändern Sie nicht vorsorglich den Buildknoten oder die gesamte Toolchain.

Zuletzt geprüft am 09.10.2026 anhand der Apple-Release-Notes zu Xcode 27.2 und der Apple-Dokumentation zu Plattformbedingungen.

Diese Anleitung ist für Sie gedacht, wenn Sie iOS- und Mac-Catalyst-Code gemeinsam pflegen und eine Plattformgrenze von einem allgemeinen Buildfehler unterscheiden müssen.
Sie verantworten Xcode CI und müssen beide Buildziele nachvollziehbar abnehmen.
Oder Sie betreiben den Mac-Buildknoten und brauchen einen belastbaren Vergleich statt eines einzelnen lokalen Erfolgs.

SECTION 01Der bekannte Fehler ist auf einen konkreten Versionsstand begrenzt

Apple beschreibt für Xcode 27.2 Beta 2 einen Fehler beim Kompilieren von Mac-Catalyst-Code, der iOS 27.1 zugeordnete APIs verwendet. Als mögliche Abhilfe nennt die Dokumentation bedingte Kompilierung für Swift und Objective-C. Lesen Sie den Hinweis eng: Er bestätigt ein konkretes Fehlermuster für den dokumentierten Versionsstand. Er sagt nicht, dass jede Fehlermeldung mit „not found“ oder „undeclared identifier“ denselben Grund hat. (Release Notes zu Xcode 27.2)

Entscheidend ist der Unterschied zwischen Symptom und Ursache. Eine Meldung wie „cannot find“ kann zu einer API gehören, die im aktuellen Ziel nicht verfügbar ist. Sie kann aber ebenso entstehen, wenn ein Modul nicht eingebunden wurde, eine Abhängigkeit eine andere Version verwendet oder ein Build Setting für das Ziel abweicht. Ein Tippfehler oder ein fehlerhaftes Import-Statement bleibt ebenfalls möglich.

Hinweis: Behandeln Sie den Apple-Eintrag als versionsgebunden. Wenn Sie eine andere Xcode-Version als Xcode 27.2 Beta 2 einsetzen, prüfen Sie deren eigene Release Notes und testen Sie den Fehler mit Ihrem Projekt, statt den Beta-Hinweis ungeprüft zu übertragen.

Auch der Bezug zu iOS 27.1 ist relevant: Der Hinweis betrifft APIs, die dieser Plattformversion zugeordnet sind; er ist keine pauschale Einschränkung aller APIs, die in einem iOS-Projekt vorkommen. Die Release Notes zu Xcode 27.1 helfen Ihnen, den verwendeten SDK- und Versionskontext zu prüfen. Halten Sie dabei fest, welche SDK-Auswahl tatsächlich im fehlgeschlagenen Job verwendet wurde.

Fehlerbild zuerst zuordnen

Für die Zuordnung genügt der letzte sichtbare Fehler in der Kurzansicht oft nicht. Sichern Sie den vollständigen Compilerkontext: betroffene Datei, Symbol, importierte Module, Zielplattform und den ersten Fehler in der Kette. Folgefehler können verschwinden, sobald der erste fehlende oder unzulässige Symbolzugriff geklärt ist.

SECTION 02Plattformursachen lassen sich durch einen Zielvergleich eingrenzen

Führen Sie den Vergleich mit demselben Commit aus. Wenn Ihr iOS-Build besteht, der Mac-Catalyst-Build aber am Zugriff auf eine iOS-27.1-API scheitert, ist eine Plattformgrenze plausibel. Sie ist damit noch nicht bewiesen: Prüfen Sie, ob beide Builds wirklich dieselbe Revision, dieselben Paketstände und passend gesetzte Build Settings verwenden.

Die Apple-Dokumentation zur Erstellung einer Mac-Version einer iPad-App erläutert den Mac-Catalyst-Kontext. Für die konkrete Projektkonfiguration vergleichen Sie außerdem die relevanten Einträge in Apples Xcode-Build-Settings-Referenz. Nicht jede Einstellung muss zwischen den Zielen gleich sein; wichtig ist, dass Unterschiede beabsichtigt und dokumentiert sind.

Erster Schritt: Fehler im unveränderten Checkout reproduzieren

Starten Sie mit einer sauberen, nachvollziehbaren Ausgangslage. Prüfen Sie den Commit-Hash, sichern Sie den vollständigen Log und notieren Sie Xcode-Version sowie SDK. Vermeiden Sie es, parallel Paketversionen, Build Settings und Quellcode zu ändern: Wenn sich der Fehler danach ändert, lässt sich die Ursache kaum noch einer einzelnen Änderung zuordnen.

Bauen Sie mit der Projektkonfiguration, die den Fehler tatsächlich auslöst. Ein Build in einer Entwickleroberfläche und ein CI-Aufruf können unterschiedliche Schemes, Konfigurationen oder Umgebungsvariablen verwenden. Vergleichen Sie deshalb den konkreten CI-Aufruf mit Ihrem Reproduktionsschritt, statt nur denselben Projektnamen zu verwenden.

Zweiter Schritt: beide Ziele direkt vergleichen

Bauen Sie denselben Commit ausdrücklich einmal für iOS und einmal für Mac Catalyst. Prüfen Sie dabei, ob das fehlerhafte Symbol nur im Catalyst-Ziel erscheint. Legen Sie für jeden Build mindestens diese Angaben ab:

• Commit-Hash und Scheme
• Xcode-Version und ausgewähltes SDK
• Zielplattform und Build-Konfiguration
• Vollständige Compiler-Ausgabe mit Dateipfad und Symbol
• Verwendete Paketstände und relevante Build Settings

Ein erfolgreiches iOS-Ergebnis ist ein nützlicher Vergleichspunkt, aber keine Entwarnung für Catalyst. Umgekehrt weist ein Fehler in beiden Zielen eher auf einen gemeinsamen Quellcode- oder Abhängigkeitsfehler hin. Beurteilen Sie die Ursache anhand des Symbolkontexts und des Unterschieds zwischen den Buildzielen, nicht anhand eines einzigen Textausschnitts aus dem Log.

Wenn Sie zuerst die Ursache bestimmen wollen, gehen Sie nach dieser Entscheidungsliste vor:

• Wenn der Fehler auf ein iOS-27.1-spezifisches Symbol begrenzt ist und nur beim Mac-Catalyst-Ziel auftritt, dann prüfen Sie die API-Zuordnung und testen Sie die dokumentierte bedingte Kompilierung.
• Wenn dasselbe Symbol in beiden Zielen fehlt, dann prüfen Sie Import, Abhängigkeit, Paketstand und Schreibweise, bevor Sie Plattformcode abtrennen.
• Wenn der Fehler nur in CI auftritt, dann vergleichen Sie Toolchain, SDK, Build-Aufruf und Checkout mit einer lokalen Reproduktion, statt sofort den Knoten zu ersetzen.
• Wenn das Symbol aus einem nicht änderbaren Paket stammt, dann erfassen Sie Paketversion und betroffenes Ziel und entscheiden Sie zwischen Aktualisierung, Ersatz oder vorläufiger Auslassung.
• Wenn die neue Xcode-Version den Fehler laut Release Notes behebt, dann entfernen Sie eine temporäre Umgehung erst nach erfolgreichem Projekttest für alle benötigten Ziele.

SECTION 03Bedingte Kompilierung isoliert plattformspezifische APIs

Die bedingte Kompilierung steuert, welcher Quellcode für ein Ziel übersetzt wird. Sie ist deshalb nicht mit einer Laufzeitabfrage gleichzusetzen. Wenn ein Symbol im Mac-Catalyst-Ziel bereits beim Kompilieren unbekannt ist, kann eine Laufzeitbedingung den Compiler nicht daran hindern, den betroffenen Ausdruck zu verarbeiten.

In Swift können Sie mit targetEnvironment(macCatalyst) Quellcode gezielt für Mac Catalyst ein- oder ausschließen. Apple beschreibt diese Syntax in der Dokumentation zu Swift-Kompilierbedingungen. In Objective-C kann TARGET_OS_MACCATALYST als Präprozessorbedingung dienen. Welche Seite der Bedingung den API-Aufruf enthält, hängt davon ab, auf welcher Plattform die API tatsächlich verfügbar ist.

Ein schematisches Swift-Beispiel:

#if targetEnvironment(macCatalyst)
    // Catalyst-spezifische Alternative oder bewusst ausgelassene Funktion
#else
    // Code für andere Ziele, sofern die API dort verfügbar ist
#endif

Verstehen Sie das Muster als Auswahl des Quellcodes, nicht als fertige Korrektur für jede API. Prüfen Sie die dokumentierte Verfügbarkeit des konkreten Symbols und legen Sie fest, welches Verhalten Mac Catalyst stattdessen bieten soll. Eine leere Bedingung kann zwar einen Compilerfehler beseitigen, aber zugleich einen Menüpunkt, einen Datenfluss oder eine wichtige Funktion stillschweigend entfernen.

In Objective-C gilt dieselbe Vorsicht. Platzieren Sie die Bedingung so, dass die Deklaration und sämtliche Verwendungen der nicht verfügbaren API für das betroffene Ziel nicht übersetzt werden. Eine Präprozessorbedingung um nur einen Funktionsaufruf reicht unter Umständen nicht, wenn bereits ein Typname oder eine Eigenschaft in einer gemeinsam kompilierten Deklaration auf die API verweist.

Praxisregel: Bevor Sie einen Codeblock ausschließen, schreiben Sie auf, welches Verhalten auf iOS erhalten bleiben muss und welche Catalyst-Alternative vorgesehen ist. Sonst besteht die Gefahr, dass der Build wieder grün ist, aber das gemeinsame Produktverhalten unbemerkt auseinanderläuft.

SECTION 04Gemeinsam genutzter Code und Abhängigkeiten brauchen getrennte Prüfungen

Suchen Sie den problematischen Zugriff nicht nur im App-Target. Er kann in einem gemeinsam genutzten Modul, einer lokalen Bibliothek oder einem Drittanbieterpaket liegen. Der Ort bestimmt, welche Änderung sinnvoll ist: Im eigenen App-Code können Sie häufig eine Zielbedingung präzise setzen. In einer gemeinsam genutzten Bibliothek müssen Sie zusätzlich sicherstellen, dass die iOS-Seite denselben API-Zugriff behält.

Bei einem Drittanbieterpaket beantworten Sie zunächst drei Fragen: Welche Version wird tatsächlich aufgelöst? Wird das Paket für beide Ziele eingebunden? Können Sie die betroffene Stelle ändern oder stammt sie aus einer unveränderbaren Abhängigkeit? Erst mit diesen Angaben lässt sich zwischen einem Paketupdate, einem Ersatz oder einer befristeten Auslassung entscheiden. Notieren Sie die Begründung, damit ein späterer Paketwechsel nicht versehentlich die Umgehung wieder entfernt oder unnötig fortschreibt.

Die folgende Gegenüberstellung hilft Ihnen, den Umfang der Korrektur vor einer Änderung einzugrenzen:

Ein Ziel kann einen anderen Zweig des gemeinsamen Codes kompilieren, während der andere Zweig für iOS weiterhin erforderlich ist. Verifizieren Sie daher nicht nur, dass Catalyst wieder kompiliert, sondern auch, dass der iOS-Zweig die ursprüngliche Funktion enthält und erreichbar bleibt. Wo sich das Verhalten unterscheidet, ergänzen Sie gezielte Tests oder dokumentieren Sie eine bewusste Produktgrenze.

SECTION 05Die CI-Abnahme prüft beide Ziele und den tatsächlichen Freigabepfad

Führen Sie die Korrektur zunächst lokal oder in einem reproduzierbaren Testjob aus, und übernehmen Sie sie anschließend in die tatsächliche CI-Ausführung. Der entscheidende Vergleich ist nicht „mein Rechner gegen den Server“ im Allgemeinen, sondern derselbe Commit mit dokumentierter Toolchain und denselben Zielabsichten.

Arbeiten Sie die Abnahme in dieser Reihenfolge ab:

• Erfassen Sie Commit, Xcode-Version, SDK, Scheme und Zielplattform vor der Änderung.
• Bauen Sie den unveränderten Stand für iOS und Mac Catalyst und sichern Sie beide Logs.
• Ändern Sie nur die notwendige Plattformbedingung oder Abhängigkeit; halten Sie die Motivation im Commit fest.
• Bauen Sie anschließend beide Ziele erneut mit demselben Commit und vergleichen Sie die Fehlermeldungen.
• Führen Sie für jedes Ziel die im Projekt vorgeschriebenen Tests aus. Wenn Ihre Freigabe ein Archiv erfordert, prüfen Sie auch den Archivierungsschritt.
• Bewahren Sie Ergebnis, vollständiges Log und Toolchain-Angaben gemeinsam auf, damit ein späterer Wechsel der Xcode-Version vergleichbar bleibt.

Ein erfolgreicher Compile ist nicht automatisch ein erfolgreicher Freigabeprozess. Wenn Sie für iOS und Mac Catalyst unterschiedliche Tests, Signierungsschritte oder Distributionswege nutzen, müssen diese Schritte ebenfalls ihrer jeweiligen Zielkonfiguration zugeordnet werden. Apples Dokumentation zur Verteilung von Apps für Beta-Tests und Releases beschreibt Distributionsschritte, die über das reine Übersetzen hinausgehen. Wenn registrierte Geräte Teil Ihres iOS-Verteilungswegs sind, prüfen Sie den dafür vorgesehenen Ablauf separat anhand der Dokumentation zur Verteilung an registrierte Geräte.

Bei einem Fehler, der nur auf einem Remote-Mac auftritt, vergleichen Sie zunächst die protokollierten Bedingungen: Werkzeugversion, SDK, Checkout und Build-Aufruf. Ein abweichender Knoten kann die Reproduktion erschweren; daraus folgt aber nicht automatisch, dass die Maschine die Ursache ist. Umgekehrt reicht eine lokale erfolgreiche Kompilierung nicht aus, um einen CI-Fehler zu schließen, wenn die CI-Abnahme ein anderes Ziel oder einen zusätzlichen Archivierungsschritt umfasst.

Wenn Apple den bekannten Fehler für eine spätere Xcode-Version als behoben aufführt, prüfen Sie diese Aussage gegen Ihr Projekt und Ihre CI-Toolchain. Entfernen Sie die bedingte Umgehung nur, wenn die betroffenen Buildziele erneut erfolgreich sind und die Korrektur weder iOS-Funktionen noch den Catalyst-Build beschädigt. So bleibt eine temporäre Maßnahme auch tatsächlich temporär und wird nicht aufgrund einer Release-Note allein als erledigt markiert.

Entscheidung nach Fehlerort und Betriebsbedarf

• Wenn Sie den Fehler mit Xcode 27.2 Beta 2, einem iOS-27.1-spezifischen Symbol und ausschließlich im Catalyst-Ziel reproduzieren, dann testen Sie die von Apple beschriebene Kompilierbedingung und dokumentieren Sie die Umgehung.
• Wenn Sie denselben Fehler nicht eindeutig auf dieses Muster zurückführen können, dann behandeln Sie ihn als gewöhnlichen Buildfehler und prüfen Abhängigkeiten, Importe und Settings.
• Wenn die Korrektur auf einem Entwickler-Mac besteht, aber im Remote-Mac-CI nicht, dann vergleichen Sie zuerst die protokollierten Umgebungen und Zielaufrufe; tauschen Sie den Knoten erst aus, wenn der Unterschied tatsächlich auf den Ausführungsknoten zurückgeht.
• Wenn regelmäßige Apple-Toolchain-Builds Teil Ihres Betriebs sind, dann halten Sie einen reproduzierbaren Mac-Buildpfad bereit. Bei seltenen Tests kann eine bestehende lokale oder CI-Umgebung ausreichend sein; entscheiden Sie anhand Ihrer Wiederholbarkeit und tatsächlichen Auslastung, nicht aufgrund dieses einzelnen Fehlers.

Falls Sie für den Vergleich erst eine Remote-Mac-Umgebung evaluieren, finden Sie den Einstieg über die MACNOX-Übersicht zu Remote-Macs. Prüfen Sie vor einer Entscheidung die MACNOX-Preisinformationen und gleichen Sie Laufzeit, Zugriffsweg und Ihre Anforderungen an Protokollierung mit Ihrem Buildbetrieb ab. Dieser Artikel behauptet keine bestimmte Konfiguration, Verfügbarkeit oder Leistung; solche Angaben müssen Sie anhand der aktuellen Angebotsinformationen und Ihrer eigenen Build-Abnahme verifizieren.

SECTION 06Häufige Fragen zu Xcode 27.2 und Mac Catalyst

Warum findet der Mac-Catalyst-Build eine iOS-API nicht?

Apple dokumentiert für Xcode 27.2 Beta 2 einen Mac-Catalyst-Compilerfehler bei der Verwendung bestimmter iOS-27.1-spezifischer APIs. Das ist ein versionsbezogener bekannter Fehler, keine allgemeine Aussage über jedes Catalyst-Projekt. Prüfen Sie zuerst, ob genau dieses Muster vorliegt, und vergleichen Sie den Fehler mit den aktuellen Release Notes, bevor Sie Änderungen an der Toolchain vornehmen.

Wie trenne ich iOS-spezifischen Code für Mac Catalyst ab?

Verwenden Sie in Swift eine Kompilierbedingung mit targetEnvironment(macCatalyst), in Objective-C die Präprozessorbedingung TARGET_OS_MACCATALYST. Damit steuern Sie, welcher Quellcode für das jeweilige Ziel übersetzt wird. Die Bedingung muss zur tatsächlichen Plattformzugehörigkeit der API passen; ein Laufzeittest kann einen Symbolfehler während der Kompilierung nicht beheben.

Was sagt ein erfolgreicher iOS-Build bei einem fehlgeschlagenen Catalyst-Build aus?

Er belegt nur, dass der iOS-Zielbuild mit diesem Commit und seiner Konfiguration erfolgreich war. Er beweist weder, dass eine verwendete API auch für Mac Catalyst verfügbar ist, noch dass beide Ziele dieselben Abhängigkeiten und Build-Einstellungen verwenden. Bauen Sie denselben Commit ausdrücklich für Mac Catalyst und prüfen Sie Symbol, Modul, SDK und vollständige Fehlermeldung.

Welche Prüfungen gehören nach der Korrektur in die Remote-Mac-CI?

Führen Sie auf dem tatsächlich verwendeten Mac-Buildknoten die iOS- und Mac-Catalyst-Builds mit demselben Commit aus. Falls Ihr Freigabeprozess Tests oder ein Archiv verlangt, prüfen Sie auch diese Schritte je Ziel. Protokollieren Sie Xcode-Version, SDK, Zielplattform und vollständige Ausgabe; ein lokaler Erfolg allein schließt Unterschiede in der CI-Umgebung nicht aus.

Wenn Ihr aktueller Buildpfad an einer nicht reproduzierbaren lokalen Umgebung, konkurrierender CI-Nutzung oder fehlender Trennung der Zielprotokolle leidet, behebt ein zusätzlicher Mac nicht automatisch den API-Fehler; er kann Ihnen aber einen getrennten, kontrollierbaren Ausführungspfad geben. Für sporadische Reproduktionen oder befristete Toolchain-Tests kann ein Mac auf Zeit sinnvoller sein als ein Hardwarekauf. Bei dauerhaft hoher Auslastung, nötigen physischen Schnittstellen oder strengen Anforderungen an lokale Kontrolle ist ein eigener Mac dagegen oft die passendere Wahl. Wenn Sie diese Ausführungsmöglichkeit für einen begrenzten Testzeitraum prüfen möchten, vergleichen Sie Ihre CI-Anforderungen mit den aktuellen MACNOX-Mietoptionen, bevor Sie einen weiteren Knoten in den Produktivbetrieb aufnehmen.