Xcode 26 build database locked: Remote-Build 2026 beheben?

Ein anonymisiertes Prüfbeispiel mit zwei nahezu gleichzeitig gestarteten xcodebuild-Jobs reicht aus, um den entscheidenden Unterschied zu zeigen: Apple beschreibt das Xcode-Buildsystem als zentralen Koordinator von Targets und Abhängigkeiten, nicht als Freigabe für beliebige parallele Schreibzugriffe auf denselben Arbeitsbereich (Apple-Dokumentation zum Buildsystem).

Symptom: Xcode 26 build database locked nach parallelem Build, SSH-Abbruch oder CI-Wiederholung.
Schnellste Lösung: Stoppen Sie zuerst konkurrierende Jobs, trennen Sie danach jeden Job auf einen eigenen DerivedData-Pfad und bereinigen Sie erst nach bestätigtem Prozessende den betroffenen Build-Zustand.

Diese Anleitung ist für Sie gedacht, wenn Sie über SSH auf einem entfernten Mac xcodebuild ausführen und nach einer getrennten Sitzung eine Datenbanksperre sehen. Sie richtet sich außerdem an kleine Teams mit parallelen CI-Jobs sowie an Betreiber einer gemeinsam genutzten Build-Maschine für Build, Test und Archive.

Die Beweiskette beginnt mit dem vollständigen Fehlerprotokoll

Bevor Sie Prozesse beenden oder Verzeichnisse löschen, sichern Sie die komplette fehlgeschlagene Kommandozeile. Der letzte Satz „build database locked“ sagt nicht, ob Build, Test, Archive oder ein verschachteltes Skript die Sperre ausgelöst hat.

Für ein anonymisiertes Protokoll sollten Projektname, Scheme, Benutzername, Hostadresse, Pfade, Bundle-ID, Team-ID und Geheimnisse ersetzt werden. Die technische Struktur muss aber erhalten bleiben. Eine verwertbare Aufzeichnung enthält mindestens:

• die vollständige xcodebuild-Zeile einschließlich -workspace oder -project, -scheme, -configuration und -derivedDataPath;
• Startzeit und Ende jedes Jobs;
• Arbeitsverzeichnis der SSH-Sitzung oder des CI-Runners;
• tatsächlich verwendete Pfade für DerivedData, OBJROOT, SYMROOT, xcresult und xcarchive;
• die erste gültige Fehlermeldung, nicht nur die abschließende Zusammenfassung;
• Prozess-ID, Elternprozess und den Auftrag, der den Prozess gestartet hat;
• die Information, ob gerade Build, Test, Archive, Export oder Upload lief.

Ein Beispiel für eine reproduzierbare, anonymisierte Kommandozeile sieht so aus:

xcodebuild \
  -workspace App.xcworkspace \
  -scheme ReleaseScheme \
  -configuration Release \
  -derivedDataPath "$WORK_ROOT/derived-data/job-$JOB_ID" \
  -resultBundlePath "$ARTIFACT_ROOT/job-$JOB_ID.xcresult" \
  clean build

Der Platzhalter JOB_ID muss pro Ausführung tatsächlich verschieden sein. Ein statischer Text wie current oder latest erzeugt zwar scheinbar einen getrennten Befehl, schreibt aber weiterhin in denselben Ordner. Die relevanten Build-Einstellungen und ihre Auflösung sollten Sie mit der Apple-Referenz zu den Build Settings gegenprüfen.

Prozess- und Zeitlinie herstellen

Prüfen Sie auf dem entfernten Mac zunächst die laufenden Prozesse, ohne pauschal alle Xcode-Prozesse zu beenden:

ps -axo pid,ppid,lstart,stat,command | grep -E '[x]codebuild|[x]code|[s]wift|[s]ourcekit'

Ordnen Sie danach jeden Treffer einem Auftrag zu. Ein xcodebuild-Prozess kann von einem CI-Runner, einer Shell, einem Skript oder einem übergeordneten Build gestartet worden sein. Entscheidend ist die Beziehung zwischen PID, PPID, Startzeit und Zielpfad. Ein älterer Prozess ist nicht automatisch der falsche; ein neuer Wiederholungsjob kann ebenso derjenige sein, den Sie behalten möchten.

Beenden Sie einen Prozess erst, wenn Sie diese vier Fragen beantworten können:

• Welcher Job hat ihn gestartet?
• In welches DerivedData- oder Ausgabe-Verzeichnis schreibt er?
• Befindet er sich noch in Build, Test, Archive oder Upload?
• Welche Ergebnisse verlieren Sie bei einer vorzeitigen Beendigung?

Ein harter Abbruch kann Testresultate unvollständig machen, ein laufendes xcarchive unbrauchbar hinterlassen oder einen Upload ohne verwertbares Abschlussprotokoll stoppen. Wenn der Prozess noch sichtbar arbeitet und der Auftrag gültig ist, hat ein normaler Abbruch Vorrang. Nur wenn er nachweislich hängt oder ein veralteter Wiederholungsversuch einen aktuellen Job blockiert, ist eine gezielte Beendigung vertretbar.

Warum tritt „Xcode 26 build database locked“ auf?

Der Fehler lässt sich für die Praxis in vier Ursachenklassen aufteilen. Diese Einteilung verhindert, dass Sie eine Pfadüberschneidung fälschlich als beschädigte Datenbank behandeln.

Reale parallele Prozesse

Die häufigste erste Spur ist ein echter gleichzeitiger Zugriff. Prüfen Sie insbesondere:

• ein versehentlich doppelt ausgelöstes Build im Terminal oder in der grafischen Oberfläche;
• einen CI-Wiederholungsversuch, dessen ursprünglicher Job nicht beendet wurde;
• einen SSH-Abbruch, bei dem die entfernte Shell oder der Prozess weiterläuft;
• zwei Nutzer, die denselben Mac und dasselbe Projektverzeichnis verwenden;
• einen Test- oder Archive-Auftrag, der noch läuft, während bereits ein neuer Build startet.

Die richtige Maßnahme ist nicht „alle Xcode-Prozesse beenden“, sondern die Job-Lebensdauer zu klären. Lassen Sie einen gültigen Auftrag weiterlaufen, wenn er noch nachvollziehbare Ergebnisse produziert. Beenden Sie den blockierenden Auftrag, sichern Sie dessen Log und starten Sie anschließend nur den fehlenden Schritt erneut.

Gemeinsame Pfade trotz unterschiedlicher Job-Namen

Zwei Jobs können in der CI-Oberfläche unterschiedlich heißen und trotzdem dieselbe physische Build-Datenbank verwenden. Das passiert, wenn der Pfad aus einem festen Projektordner berechnet wird oder eine Einstellung aus der grafischen Oberfläche die Kommandozeile überlagert.

Vergleichen Sie für jeden Job die effektiv aufgelösten Werte von:

• DerivedData;
• OBJROOT;
• SYMROOT;
• -resultBundlePath;
• -archivePath;
• temporären Export- und Upload-Verzeichnissen.

DerivedData, Build Products und Zwischenobjekte müssen pro parallelem Job isoliert sein. Ein xcresult-Bundle und ein xcarchive sollten ebenfalls nicht von zwei Jobs gleichzeitig beschrieben werden. Zentral gespeichert werden dürfen dagegen abgeschlossene Artefakte, sofern der Dateiname die Job-ID, Commit-ID oder eine andere eindeutige Zuordnung enthält.

Ein sauberer Nachweis besteht darin, zwei Jobs gleichzeitig auszuführen und danach zwei getrennte Ergebnisbündel, zwei getrennte Logs und zwei eindeutig zuordenbare Ausgabeverzeichnisse vorzufinden. Wenn einer der Jobs in das Verzeichnis des anderen schreibt, ist die Isolation nicht gegeben, auch wenn beide Prozesse zunächst erfolgreich starten.

Versteckte verschachtelte Builds

Ein Run-Script kann innerhalb eines übergeordneten xcodebuild erneut xcodebuild aufrufen. Auch Paketwerkzeuge, Cross-Project-Abhängigkeiten oder Veröffentlichungslogik können unbemerkt einen zweiten Build starten. Dann liegt nicht zwingend ein Problem der CI-Anzahl vor: Ein einzelner äußerer Job erzeugt selbst konkurrierende oder überlappende Schreibzugriffe.

Suchen Sie deshalb in Skripten, Build-Phasen und Abhängigkeiten nach weiteren Build-Aufrufen:

grep -R "xcodebuild" ./Scripts ./ci ./build-tools 2>/dev/null

Der Befehl ist nur ein Einstieg; generierte Skripte und Konfigurationen müssen Sie ebenfalls berücksichtigen. Apple erklärt, wie Custom Scripts während eines Builds eingebunden werden und welche Eingaben und Ausgaben dafür deklariert werden sollten.

Schalten Sie nicht vorschnell jede parallele Build-Option ab. Klären Sie zuerst:

1. Warum ruft das Skript erneut xcodebuild auf?
2. Welches Ziel besitzt den erzeugten Output?
3. Muss der innere Build wirklich innerhalb des äußeren Builds stattfinden?
4. Wer ist für das Löschen oder Archivieren dieses Outputs zuständig?
5. Wie kann der alte Ablauf zurückgesetzt werden?

Nach der Änderung muss das Build-Log zeigen, dass der innere Auftrag nicht mehr unkontrolliert gestartet wird. Ein vermeintlich behobener Fehler ohne überprüfbare Prozessgrenze ist keine stabile Reparatur.

Getrennte Pfade sind die zentrale CI-Entscheidung

Die folgende Gegenüberstellung hilft Ihnen, den vorhandenen Aufbau zu bewerten. Sie ersetzt keine Logprüfung; sie zeigt, welche Entscheidung bei welchem Befund sinnvoll ist.

Die Pfade explizit ausgeben

Setzen Sie nicht nur -derivedDataPath, sondern prüfen Sie auch, ob Ihr Projekt andere Ausgabepfade festlegt. Ein Job kann sein DerivedData korrekt trennen und trotzdem ein gemeinsames Archive-Verzeichnis verwenden.

Für jeden Lauf sollten Log und Verzeichnisstruktur mindestens diese Zuordnung enthalten:

job-<eindeutige-id>/
  derived-data/
  result.xcresult/
  archive.xcarchive/
  build.log
  process-summary.txt

Verwenden Sie in dieser Darstellung keine realen Team-IDs, Zugangsdaten oder Hostnamen. Signierungsgeheimnisse gehören nicht in Build-Logs. Die Xcode-Dokumentation zur Konfiguration von Target-Build-Einstellungen ist maßgeblich, wenn ein Ziel eigene Ausgabewerte oder Konfigurationsdateien einführt.

Bereinigung erst nach bestätigtem Prozessende

Wenn keine relevanten xcodebuild-, Test- oder Indexprozesse mehr laufen, prüfen Sie, ob die Sperre durch einen abgebrochenen Auftrag zurückgeblieben ist. Gehen Sie dabei von klein nach groß vor:

1. Sichern Sie das vollständige Build-Log, xcresult, vorhandene xcarchive-Verzeichnisse und dSYM-Dateien.
2. Prüfen Sie, ob das betroffene DerivedData-Verzeichnis ausschließlich zu dem fehlgeschlagenen Job gehört.
3. Benennen Sie den einzelnen Job-Ordner um, statt sofort den gesamten Benutzer-Cache zu löschen.
4. Starten Sie denselben xcodebuild-Befehl mit einer neu erzeugten, eindeutig benannten Arbeitsstruktur.
5. Vergleichen Sie den ersten Fehler, Prozessverlauf und Output mit dem vorherigen Lauf.
6. Erweitern Sie die Bereinigung nur, wenn der Fehler im Projektbereich reproduzierbar bleibt und keine gültigen Artefakte betroffen sind.

Die Reihenfolge ist wichtig. Ein vollständiges Löschen von DerivedData kann eine beschädigte Wiederverwendung umgehen, beweist aber nicht, dass die Parallelität beseitigt wurde. Wenn zwei Jobs weiterhin denselben Pfad verwenden, erscheint die Sperre beim nächsten Lauf erneut.

Archive und Signierung getrennt schützen

Ein xcarchive ist nicht dasselbe wie ein temporäres Build-Verzeichnis. Bewahren Sie abgeschlossene Archive, dSYM-Dateien, Exportprotokolle und Signierungsassets außerhalb des Bereichs auf, den ein Bereinigungsschritt entfernen darf. Apple beschreibt den Ablauf für signierten Distributionscode für macOS; die konkrete Projektkonfiguration kann davon abweichen, die Trennung von temporären und dauerhaft benötigten Daten bleibt jedoch eine sinnvolle Sicherheitsgrenze.

Löschen Sie niemals anhand eines zu allgemein formulierten Musters wie dem gesamten Benutzerverzeichnis. Prüfen Sie den absoluten Pfad, den Besitzer und die Job-Zuordnung. Bei einem gemeinsam genutzten Mac kommt zusätzlich die Berechtigungsebene hinzu: Ein Prozess eines anderen Benutzers kann weiterlaufen, während Ihre eigene Shell keinen vollständigen Einblick in dessen Dateien oder Umgebung besitzt.

Checkliste für die Wiederherstellung und Abnahme

Arbeiten Sie die folgende Liste in der angegebenen Reihenfolge ab:

• [ ] Vollständige xcodebuild-Zeile, Arbeitsverzeichnis und erster gültiger Fehler sind gesichert.
• [ ] Build, Test, Archive und Upload sind dem jeweils auslösenden Prozess zugeordnet.
• [ ] Laufende Prozesse wurden anhand von PID, PPID, Startzeit und Pfad bewertet.
• [ ] Ein gültiger Job wurde nicht ohne Prüfung seiner Artefakte beendet.
• [ ] Jeder parallele Job besitzt einen eigenen DerivedData-Pfad.
• [ ] OBJROOT, SYMROOT, xcresult und xcarchive überschneiden sich nicht unkontrolliert.
• [ ] Run-Scripts und Abhängigkeiten lösen keinen unerwarteten inneren Build aus.
• [ ] Zwischenprodukte, Logs, dSYM-Dateien und Archive sind getrennt verwaltet.
• [ ] Die betroffene Bereinigung wurde erst nach bestätigtem Prozessende durchgeführt.
• [ ] Der identische Build-Befehl läuft zunächst als Einzeljob erfolgreich.
• [ ] Zwei parallele Jobs erzeugen getrennte Ergebnisbündel.
• [ ] Ein echtes Archive wurde nach der Reparatur erfolgreich abgeschlossen.
• [ ] SSH-Trennung, Job-Abbruch und Host-Neustart wurden mit dokumentierter Wiederaufnahme geprüft.

Für Tests und Ergebnisinterpretation verweist Apple auf eine eigene Dokumentation zu Testausführung und Testergebnissen. Nutzen Sie diese Auswertung, um einen formal erfolgreichen Prozess von einem tatsächlich vollständigen Testlauf zu unterscheiden.

Abnahme in drei Stufen statt sofortiger Parallelbetrieb

Beginnen Sie mit einem einzelnen Build ohne konkurrierenden Auftrag. Dabei muss der Pfad neu angelegt werden können und der Log eindeutig dem Job gehören. Erst wenn dieser Lauf stabil ist, aktivieren Sie parallele Tests mit getrennten Arbeitsverzeichnissen.

Führen Sie danach eine echte Archive-Ausführung aus. Ein erfolgreicher Build allein beweist nicht, dass Archive-Pfad, Signierung, Export und Artefaktablage korrekt getrennt sind. Die Apple-Hinweise zu CI-Workflows für Swift Packages und Apps sind für die Struktur automatisierter Abläufe relevant; prüfen Sie trotzdem Ihre konkrete Job- und Pfadauflösung.

Zum Abschluss simulieren Sie drei Störfälle:

1. Die SSH-Verbindung wird getrennt, während der Build noch läuft.
2. Ein Job wird abgebrochen und anschließend neu gestartet.
3. Der Remote-Mac wird neu gestartet, bevor Logs und Artefakte abgeholt wurden.

Nach jedem Störfall muss klar sein, welcher alte Prozess beendet wurde, welche Verzeichnisse wiederverwendet werden dürfen und wo der neue Lauf seine Ergebnisse ablegt. Wenn Sie das nicht anhand von Logs und Prozessdaten beantworten können, ist die Umgebung noch nicht für unbeaufsichtigte Archive geeignet.

Die passende Gegenmaßnahme bei wiederkehrenden Fehlern

Tritt die Sperre trotz eindeutiger Pfade erneut auf, unterscheiden Sie zwischen drei Fällen:

• Bei echter Überlappung korrigieren Sie Prozesssteuerung und Job-Abbruch.
• Bei wiederholter Pfadkollision überarbeiten Sie die Berechnung von DerivedData, OBJROOT, SYMROOT und Archive-Ausgabe.
• Bei einem einzelnen, sauber isolierten Job mit wiederkehrendem beschädigtem Zustand erweitern Sie die gezielte Bereinigung und prüfen die aktuelle Xcode-26-Dokumentation sowie die Release Notes.

Apple veröffentlicht Änderungen und Hinweise in den Xcode-26-Release-Notes. Behandeln Sie Entwicklerforum-Fälle nur als Hinweise für mögliche Reproduktionsbedingungen, nicht als allgemeine Zusage für jede Xcode-26-Installation.

Wenn die Maschine keine zuverlässige Prozesskontrolle, keine getrennten Arbeitsverzeichnisse oder keinen dauerhaft laufenden Dienst bereitstellt, sind weitere lokale Workarounds meist schlechter als eine isolierte Build-Umgebung. Ein Wechsel auf einen anderen Runner sollte aber erst erfolgen, nachdem Sie die Pfad- und Prozessdaten gesichert haben; sonst übertragen Sie denselben Fehler lediglich auf einen anderen Host.

FAQ: Fehlerbild, SSH-Reste und DerivedData

Die folgenden Antworten decken die typischen Such- und Entscheidungsfragen ab, ohne aus der Fehlermeldung eine allgemeingültige Ursache abzuleiten.

Was Sie vor dem nächsten Remote-Build entscheiden sollten

Bevor Sie Ihre bestehende Umgebung ersetzen, führen Sie den Einzel-Build, zwei getrennte parallele Jobs, eine SSH-Unterbrechung und einen Neustart-Test aus. Kann der aktuelle Host danach Prozesse sauber zuordnen, eigene Arbeitsverzeichnisse erzeugen und Archive samt Logs wiederherstellen, genügt meist eine Anpassung der CI-Konfiguration.

Bleiben dagegen gemeinsame Pfade, nicht kontrollierbare Restprozesse oder unvollständige Artefakte bestehen, ist ein dauerhaft betriebener Remote-Mac mit klarer Job-Isolation die passendere Architektur. Ein Mac-Build- und Wiederherstellungskonzept hilft Ihnen bei der Planung von Artefaktsicherung und Wiederanlauf. Wenn Sie dafür nur zeitweise eine kontrollierbare macOS-Umgebung benötigen, können Sie die verfügbaren KVMFLUX-Mietmodelle anhand von Zugriffsrechten, Laufzeit und CI-Anbindung prüfen.

Ein gemeinsam genutzter Rechner ohne getrennte Pfade spart zwar zunächst Verwaltungsaufwand, verursacht aber bei SSH-Abbrüchen, Wiederholungsjobs und parallelen Archives schwer nachvollziehbare Fehler. Eine lokale Anschaffung bindet dagegen Kapital und lässt sich für kurzfristige Tests oder wechselnde Projekte nicht ebenso flexibel zurückbauen. Für vorübergehende Build- und Testphasen ist ein gemieteter Mac deshalb dann die vernünftigere Option, wenn Sie vollständige Prozesskontrolle, Root-Zugriff und einen dauerhaft erreichbaren Host benötigen; für eine langfristig konstante Schwerlastumgebung oder zwingende physische Schnittstellen bleibt eigene Hardware die ehrlichere Wahl.

Weiterlesen

• Xcode-CI auf einem Cloud-Mac zuverlässig ausführen
• Parallele macOS-Builds mit einem selbst verwalteten Remote-Runner organisieren
• Xcode Cloud oder eigener Mac-CI-Server: Die passende Architektur wählen