Ein einzelner Upload kann an mehreren Stellen scheitern: Seit dem 01.11.2023 akzeptiert Apples Notarisierungsdienst altool nicht mehr; für die Kommandozeile ist notarytool der vorgesehene Weg (Technische Notiz TN3147). Bei einem macOS App Notarisierungsfehler sollten Sie deshalb nicht dasselbe Artefakt blind erneut einreichen. Sichern Sie zuerst Status und Log, prüfen Sie danach das finale ZIP-, DMG- oder PKG-Produkt, reparieren Sie die Signierung von innen nach außen und akzeptieren Sie „Accepted“ erst nach Stapling, Gatekeeper-Test und Installation in einer unabhängigen Umgebung als veröffentlicht.

Wer sollte diese Anleitung lesen?
Sie verteilen eine macOS-App außerhalb des Mac App Store mit Developer ID, etwa über Ihre Website, einen DMG-Download, ein ZIP-Archiv oder ein PKG.
Sie betreiben einen Remote Mac oder eine CI-Automatisierung mit notarytool und stapler oder veröffentlichen Apps mit Plug-ins, Hilfsprogrammen und weiteren verschachtelten Komponenten.

Ihre Zeitachse: Status sichern, dann erst reparieren

Ein Notarisierungsfehler ist kein einzelner Fehlerzustand. Build, Archive, Export, Sign, Package, Submit, Accepted, Staple und Gatekeeper liegen auf unterschiedlichen Stationen. Wenn Sie diese Stationen vermischen, löschen Sie möglicherweise genau die Beweise, die den Fehler erklären.

Meilenstein Was Sie sichern oder prüfen Entscheidung
Submit Submission-ID, Kommandoausgabe, Dateiname und Prüfsumme Bei fehlender ID zuerst Authentifizierung oder Upload prüfen
Processing Statusabfrage und Warteprotokoll Nicht parallel mit verändertem Artefakt weitermachen
Invalid Vollständiger Log mit Pfaden und erstem gültigem Fehler Erst Ursache beheben, dann neu signieren und verpacken
Accepted Status, Log und eingereichte Prüfsumme Noch nicht als fertige Veröffentlichung behandeln
Staple / Validate Ticket am vorgesehenen Artefakt Bei Fehlern Verpackung und Ticket-Ziel prüfen
Gatekeeper Download- und Installationsprüfung auf unabhängigem Mac Erst danach den Release-Link freigeben

Speichern Sie mindestens die Submission-ID, den exakten Inhalt der Terminalausgabe, den finalen Dateinamen, die Prüfsumme des eingereichten Artefakts und den verwendeten Xcode-Pfad. Entfernen Sie Zertifikate, ändern Sie Credentials oder überschreiben Sie signierte Dateien erst, wenn Sie eine Rückfallkopie des aktuellen Release-Artefakts erstellt haben.

Erste Etappe: Das finale Distributionsartefakt statt das Projekt untersuchen

Ein häufiger Denkfehler ist die Prüfung des App-Bundles, das aus Xcode exportiert wurde, während tatsächlich ein später verändertes ZIP oder ein neu erzeugtes DMG hochgeladen wird. Für den macOS App Notarisierungsfehler zählt ausschließlich das Objekt, das notarytool erhalten hat.

Prüfen Sie daher in dieser Reihenfolge:

  1. Kopieren Sie das finale ZIP, DMG oder PKG in ein separates Prüfverzeichnis. Arbeiten Sie nicht auf der einzigen Release-Kopie.
  2. Ermitteln Sie die Prüfsumme und notieren Sie Dateigröße, Dateiname und Erstellungszeitpunkt. Die Werte dienen später zum Abgleich zwischen lokalem Rechner, Remote Mac und Upload.
  3. Prüfen Sie die äußere Developer ID-Signatur und kontrollieren Sie, ob Hardened Runtime sowie ein sicherer Zeitstempel vorhanden sind.
  4. Untersuchen Sie alle verschachtelten ausführbaren Bestandteile: Frameworks, Plug-ins, Login Items, XPC-Dienste, Helper und eingebettete Werkzeuge.
  5. Vergleichen Sie die Entitlements mit dem tatsächlich benötigten Verhalten. Ein unnötiges get-task-allow oder ein formal fehlerhaftes Entitlement kann die Notarisierung verhindern.
  6. Prüfen Sie, ob nach der Signierung noch Dateien im Bundle ersetzt, komprimiert, gepatcht oder aus einem Build-Verzeichnis kopiert wurden.

Apple beschreibt die Anforderungen an Signierung, Hardened Runtime und Notarisierung im offiziellen Ablauf für die Verteilung von macOS-Software (Anleitung zur Notarisierung vor der Verteilung). Der entscheidende Praxispunkt lautet: Jede Änderung am Bundle nach der Signatur macht die vorherige Prüfung für diesen Teil des Produkts wertlos.

Hinweis: Signieren Sie nicht vorsorglich alles erneut, solange Sie den betroffenen Pfad nicht kennen. Eine pauschale Neusignierung kann die ursprüngliche Ursache verdecken und macht einen Vergleich mit dem vorherigen Artefakt schwieriger.

Signaturprüfung ist eine Kette, kein einzelner Haken

Prüfebene Typischer Befund Was Sie daraus ableiten
App-Bundle Äußere Signatur wirkt gültig Verschachtelte Inhalte sind noch nicht automatisch ausgeschlossen
Framework oder Plug-in Eigene Signatur fehlt oder passt nicht Komponente zuerst reparieren
Hilfsprogramm oder XPC-Dienst Falsches Zertifikat oder Entitlement Ursprung und Zweck der Komponente klären
ZIP oder DMG Container nach Signierung verändert Neu verpacken und den äußeren Ablauf wiederholen
PKG Installer signiert, enthaltene Payload problematisch Installierte ausführbare Inhalte separat bewerten

Die offizielle Dokumentation zum Verpacken von Mac-Software für die Distribution hilft dabei, Export und Packaging voneinander zu trennen. Das ist wichtig, weil ein erfolgreiches Archive nicht automatisch ein korrektes, unverändertes Submit-Artefakt ergibt.

Zweite Etappe: notarytool-Log nach dem ersten gültigen Fehler lesen

Zeigt notarytool „Invalid“, benötigen Sie die Submission-ID und den zugehörigen Log. Rufen Sie nicht nur den Status erneut ab. Der Status sagt, dass die Prüfung fehlgeschlagen ist; der Log zeigt, welcher Pfad und welche Regel betroffen sind.

Eine sichere Diagnosefolge sieht so aus:

  1. Lesen Sie die Statusinformation mit der ursprünglichen Submission-ID aus.
  2. Laden Sie den vollständigen Log für genau diese ID.
  3. Suchen Sie nach dem ersten Eintrag, der einen konkreten Pfad, eine konkrete Komponente oder eine konkrete Regel nennt.
  4. Gruppieren Sie nach Ursache, statt jede spätere Folgefehlermeldung einzeln zu reparieren.
  5. Bewahren Sie den unveränderten Log zusammen mit dem zugehörigen Artefakt auf.

Apple führt typische Ursachen wie ungültige Signaturen, fehlende sichere Zeitstempel, problematische Entitlements und Fehler in verschachtelten Komponenten in der Übersicht zur Fehlerbehebung bei der Notarisierung zusammen.

Erster konkreter Hinweis im Log Wahrscheinliche Fehlerzone Begrenzte Reparatur
Signatur ungültig oder Code nicht signiert Betroffene Binärdatei oder verschachtelte Komponente Nur den betroffenen Bestandteil prüfen und von innen nach außen signieren
Sicherer Zeitstempel fehlt Signierkommando oder verwendete Signaturidentität Signaturprozess und Zertifikatsauswahl kontrollieren
get-task-allow oder Entitlement-Fehler Exportprofil oder Entitlements-Datei Entitlement auf den vorgesehenen Release-Zweck begrenzen
Falscher Zertifikatstyp Verwechslung von Entwicklungs-, Distribution- oder Developer-ID-Pfad Release-Zertifikat und Zielplattform abgleichen
Konkreter Framework-, Plug-in- oder Helper-Pfad Verschachtelter Code wurde ausgelassen oder später ersetzt Komponente einzeln korrigieren, danach Eltern-Bundle neu behandeln

Diese Zuordnung ist kein Ersatz für den Log. Besonders bei verschachtelten Produkten kann die erste sichtbare Meldung nur eine Folge eines früheren Packaging-Fehlers sein. Wenn der Dienst über längere Zeit im Status „Processing“ bleibt, prüfen Sie zusätzlich den offiziellen Systemstatus, bevor Sie das Artefakt verändern. Eine vermutete Dienststörung aus einem Forum ist kein ausreichender Beleg für die Ursache Ihres Releases.

Dritte Etappe: Von innen nach außen neu signieren und verpacken

Die Reparaturreihenfolge entscheidet darüber, ob Sie einen echten Fehler beheben oder nur eine neue Signatur über eine unverstandene Struktur legen. Beginnen Sie mit dem am tiefsten verschachtelten ausführbaren Bestandteil. Danach folgen Frameworks, Plug-ins, Hilfsprogramme und das App-Bundle. Erst am Ende behandeln Sie Container wie DMG oder PKG.

ZIP, DMG und PKG nicht gleich behandeln

Distributionsform Was Sie zuerst kontrollieren Was danach folgt
ZIP mit App App-Struktur, Signatur und unveränderte Archivierung Neues ZIP aus dem reparierten App-Bundle erzeugen
DMG Signiertes App-Bundle und Inhalt des Disk-Images DMG neu erstellen, äußere Eigenschaften prüfen und geeignet einreichen
PKG Installer-Signatur und alle ausführbaren Inhalte der Payload Packaging-Workflow und mögliche zusätzliche Notarisierungsschritte prüfen

Die offizielle Apple-Anleitung zum Anpassen des Notarisierungs-Workflows ist die richtige Referenz, wenn Ihr Installer weitere ausführbare Inhalte auf dem Zielsystem ablegt. Ein signierter Installer beweist nicht automatisch, dass jede später installierte Komponente dieselben Anforderungen erfüllt.

Wenn Sie eine Komponente ersetzen, müssen Sie die darüberliegende Signaturkette erneut aufbauen. Ändern Sie nach der Signierung weder Info-Properties noch eingebettete Frameworks, Plug-ins oder Hilfsprogramme. Erzeugen Sie anschließend das finale Distributionsformat neu und laden Sie genau diese Datei hoch. Verwechseln Sie dabei nicht den Build mit dem Archive, das Archive mit dem Export oder den Export mit dem Package.

Wann Sie Credentials oder Zertifikate nicht sofort austauschen sollten

Wenn der Log auf einen konkreten Bundle-Pfad, ein Entitlement oder einen fehlenden Zeitstempel zeigt, ist ein Credential-Wechsel keine zielgerichtete Reparatur. Das Löschen eines Zertifikats kann lokale Builds, andere Entwickler und laufende Veröffentlichungen beeinträchtigen. Sichern Sie zuerst die aktuelle Credential-Zuordnung und dokumentieren Sie, welche Identität der fehlgeschlagene Prozess verwendet hat.

Ein Wechsel ist erst sinnvoll, wenn Sie nachweisen können, dass die verwendete Identität abgelaufen, nicht für den vorgesehenen Veröffentlichungsweg bestimmt oder auf dem Remote Mac nicht verfügbar ist. Danach müssen Sie nicht nur die Schlüsselbundkonfiguration, sondern auch den Signier- und Rückfallprozess testen.

Vierte Etappe: „Accepted“ durch Stapling und Gatekeeper bestätigen

„Accepted“ bedeutet, dass der Notarisierungsdienst die eingereichte Datei akzeptiert hat. Es bedeutet nicht automatisch, dass Sie die richtige Datei veröffentlichen, dass ein Ticket eingebettet wurde oder dass der Download auf einem fremden Mac funktioniert.

Führen Sie nach dem Accepted-Ergebnis diese Prüfungen aus:

  1. Vergleichen Sie Submission-ID und Prüfsumme mit dem Artefakt, das Sie veröffentlichen möchten.
  2. Verwenden Sie stapler auf dem dafür geeigneten Distributionsobjekt.
  3. Validieren Sie das eingebettete Ticket mit dem passenden Stapler-Prüfschritt.
  4. Laden Sie die veröffentlichte Datei in ein sauberes Testverzeichnis oder auf einen unabhängigen Mac.
  5. Führen Sie eine Gatekeeper-Bewertung aus und installieren beziehungsweise starten Sie die App wie ein normaler Nutzer.
  6. Wiederholen Sie den Test mit eingeschränkter oder nicht verfügbarer Netzwerkverbindung, wenn Ihr Veröffentlichungsprozess auf ein eingebettetes Ticket angewiesen ist.

Testen Sie nicht die Datei im Build-Ordner, während der Download aus dem CDN oder Webserver ein anderes Archiv liefert. Ein nachträglich umbenanntes, neu gepacktes oder ausgetauschtes Artefakt kann wieder eine andere Signatur und damit einen neuen macOS App Notarisierungsfehler besitzen.

Entscheidungshilfe für die nächste Aktion

  • Wenn der Upload keine verwertbare Submission-ID erzeugt, dann prüfen Sie Authentifizierung, Credential-Quelle, Netzwerk und den verwendeten notarytool-Aufruf. Sonst gehen Sie zum Log über.
  • Wenn der Log einen konkreten Pfad nennt, dann reparieren Sie zuerst diese tiefste betroffene Komponente. Sonst prüfen Sie Packaging, Zertifikatstyp und Entitlements gemeinsam.
  • Wenn das App-Bundle nach der Signierung verändert wurde, dann verwerfen Sie die frühere Prüfung und erstellen Sie ein neues finales Artefakt. Sonst behalten Sie die Prüfsumme als Vergleichswert.
  • Wenn der Status Accepted lautet, aber Stapling oder Validierung scheitert, dann veröffentlichen Sie die Datei noch nicht. Prüfen Sie Container, Ticket-Ziel und die tatsächlich verwendete Datei.
  • Wenn die lokale Prüfung funktioniert, der Remote Mac jedoch ein anderes Ergebnis liefert, dann vergleichen Sie Xcode-Pfad, Credential-Quelle, Schlüsselbund, Arbeitsverzeichnis und Artefakt-Prüfsumme. Sonst suchen Sie weiter im serverseitigen Log.
  • Wenn Sie eine App dauerhaft mit privaten Signaturschlüsseln veröffentlichen, dann verwenden Sie eine isolierte, protokollierte Umgebung mit begrenzten Zugriffsrechten. Wenn der Rechner nur sporadisch benötigt wird, dann reicht zunächst eine manuell bestätigte Release-Pipeline mit dokumentiertem Rückfall.

In der ersten Woche die Remote-Mac-Pipeline stabilisieren

Ein Remote Mac ist nicht automatisch eine reproduzierbare Build- und Notarisierungsumgebung. Unterschiedliche Benutzer-Sitzungen können verschiedene Schlüsselbunde, Umgebungsvariablen, Xcode-Versionen oder Arbeitsverzeichnisse verwenden. Fixieren Sie deshalb den Entwicklerpfad über xcode-select oder DEVELOPER_DIR und schreiben Sie ihn in jedes Release-Protokoll.

Ordnen Sie jeder Ausführung mindestens diese Werte zu:

  • anonymisierte Build- oder Release-Kennung;
  • verwendeter Xcode- und Developer-Tool-Pfad;
  • Credential-Quelle und Signaturidentität;
  • Prüfsumme des finalen Artefakts;
  • Submission-ID und zugehöriger Log;
  • Ergebnis von Stapling, Validierung und Gatekeeper-Test.

Apple beschreibt die Migration zum aktuellen Kommandozeilenwerkzeug und die Abgrenzung zu älteren Abläufen in TN3147 zur modernen Notarisierung. Nutzen Sie die Anleitung nicht nur beim ersten Setup, sondern auch nach einem Xcode- oder Toolchain-Wechsel.

Ihre Automatisierung sollte außerdem einen nachvollziehbaren Warte- und Abbruchpfad besitzen. Protokollieren Sie Statusabfragen, unterscheiden Sie einen vorübergehenden Uploadfehler von einem Invalid-Ergebnis und verhindern Sie parallele Retries mit unterschiedlichen Artefakten. Bei einem Timeout muss die Pipeline an der Submission-ID ansetzen, nicht einfach ein neues Bundle erzeugen.

Testen Sie innerhalb der ersten Woche mindestens drei Betriebsfälle: eine unterbrochene SSH-Sitzung, einen Neustart des Remote Mac und eine echte Veröffentlichung mit einer nicht formellen Version. Prüfen Sie, ob Logs nach der Trennung erhalten bleiben, ob die Credential-Quelle wieder verfügbar ist und ob der nächste Build denselben Toolchain-Pfad nutzt. Wenn Ihre Entwicklungsstation diese Voraussetzungen nicht zuverlässig erfüllt, können Sie nach der lokalen Fehleranalyse Signierung, Notarisierung und Gatekeeper-Abnahme auf einen dauerhaft reservierten Remote Mac von VMSPIN verlagern. Für eine Kalkulation der laufenden Nutzung finden Sie die verfügbaren Mietmodelle für Mac-Umgebungen.

Häufige Fragen zur Fehlerdiagnose

Wie findet man nach „Invalid“ den konkreten Fehler?

Nutzen Sie die Submission-ID des fehlgeschlagenen Uploads und laden Sie den vollständigen notarytool-Log. Suchen Sie nach dem ersten Eintrag mit einem konkreten Dateipfad oder einer konkreten Regel. Bewahren Sie die unveränderte Datei, Prüfsumme und Terminalausgabe auf. Erst danach sollten Sie signieren, packen oder Credentials verändern.

Warum reicht eine gültige Signatur nicht aus?

Eine gültige äußere Signatur sagt nichts darüber aus, ob Frameworks, Plug-ins, Login Items, XPC-Dienste oder Hilfsprogramme korrekt eingebettet und signiert wurden. Zusätzlich können ein fehlender sicherer Zeitstempel, ein ungeeignetes Entitlement oder ein falscher Zertifikatstyp die Notarisierung blockieren. Prüfen Sie deshalb die gesamte Code-Signatur-Kette.

Ist Accepted bereits ein veröffentlichungsfertiges Ergebnis?

Nein. Accepted beschreibt die Entscheidung des Notarisierungsdienstes für die eingereichte Datei. Sie müssen noch prüfen, ob diese Datei tatsächlich veröffentlicht wird, ob Stapling und Validierung erfolgreich sind und ob Gatekeeper den realen Download auf einem unabhängigen Mac akzeptiert. So vermeiden Sie einen Test mit einem lokalen, aber nicht veröffentlichten Artefakt.

Was unterscheidet lokale und entfernte automatische Notarisierung?

Auf einem Remote Mac können andere Xcode-Auswahlen, Schlüsselbund-Sitzungen, Umgebungsvariablen, Arbeitsverzeichnisse und Dateien aktiv sein. Vergleichen Sie daher vor jeder Ursachenanalyse die Toolchain, Credential-Quelle, Signaturidentität und Prüfsumme. Stimmen diese Werte nicht überein, ist der Prozess nicht reproduzierbar, selbst wenn die lokale Notarisierung erfolgreich war.

Empfehlung für Ihre Release-Entscheidung

Wenn Sie weiterhin vom eigenen Entwicklungsrechner signieren, benötigen Sie stabile Schlüsselbundrechte, einen unveränderten Developer-ID-Schlüssel, eine fixierte Toolchain und dauerhaft auffindbare Logs. Ein lokaler Rechner ist für gelegentliche Releases ausreichend, wird aber problematisch, sobald er ausgeschaltet ist, mehrere Personen dieselben Credentials benötigen oder ein Release nach einer Unterbrechung reproduzierbar fortgesetzt werden muss.

Ein dauerhaft betriebener Remote Mac löst diese Punkte nicht automatisch, bietet Ihnen aber eine klar abgrenzbare Umgebung für Signierung, Notarisierung und Gatekeeper-Abnahme. Gegenüber einem ständig wechselnden lokalen Rechner vermeiden Sie vor allem drei typische Nachteile: nicht verfügbare Arbeitszeiten, driftende Xcode-Pfade und verlorene Submission-Logs. Wenn die private Schlüsselverwaltung, Zugriffsrechte und Backups sauber umgesetzt sind, ist das für kleine Teams oft die kontrollierbarere Veröffentlichungskette.

Für eine kurzfristige Release-Phase, einen externen Tester oder die Migration Ihrer Pipeline können Sie bei VMSPIN zunächst eine Mac-Umgebung mieten und mit einer nicht formellen Version prüfen, ob Build, Sign, Submit, Staple und Gatekeeper in einem vollständigen Durchlauf funktionieren. Für langfristige, sehr intensive Dauerlast oder Anforderungen an physische Anschlüsse bleibt ein eigener Mac die passendere Wahl.