Fehlerbehebung

Dieser Leitfaden konzentriert sich auf die Ausfallarten, die in der Praxis am wichtigsten sind: Config-Laden, Versionierung, Registry-Authentifizierung, Git-Zustand und CI-Verhalten.

Mit den sichersten Diagnosebefehlen beginnen

Nutze diese Befehle, bevor du einen fehlgeschlagenen Publish erneut startest:

pubm changesets status --verbose
pubm changesets version --dry-run
pubm --dry-run
pubm --mode ci --phase prepare

Zusammen beantworten diese Befehle:

• welche Version pubm zu veröffentlichen glaubt
• welche Pakete betroffen sind
• ob der Changelog-Text plausibel ist
• ob Zugangsdaten und Registry-Prüfungen bereit sind

Publish durch Git-Zustand blockiert

Symptome:

• der Release-Flow stoppt vor dem Publish
• Fehler melden einen nicht sauberen Working Tree
• Fehler melden den falschen Branch

Was du prüfen solltest:

• lokale Änderungen committen oder stashten
• bestaetigen, dass du auf dem erwarteten Branch bist
• falls das eine absichtliche Ausnahme ist, prüfen, ob --any-branch akzeptabel ist

Umgehungsflags sollten nicht in den Standard-Workflow uebernommen werden, wenn du nicht wirklich bewusst eine schwächere Release-Sicherheit willst.

Der Versionsbefehl meldet, dass keine Changesets gefunden wurden

Symptome:

• pubm changesets version gibt No changesets found. aus

Was du prüfen solltest:

• sicherstellen, dass Dateien in .pubm/changesets/ existieren
• sicherstellen, dass du im Repository-Root bist
• wenn du von .changeset/ migrierst, pubm changesets migrate ausführen

Falsche Pakete werden hochgezogen

Symptome:

• Pakete, die du nicht erwartet hast, erscheinen in changesets status
• feste oder gekoppelte Pakete bewegen sich unerwartet gemeinsam

Was du prüfen solltest:

• pubm changesets status --verbose ausführen
• die fixed- und linked-Gruppen in pubm.config.* ansehen
• verifizieren, ob das Repository independent oder fixed versioniert

Wenn die Workspace-Struktur komplex ist, lieber eine explizite packages-Config verwenden, statt nur auf Erkennung zu setzen.

Config-Datei laesst sich nicht laden

Symptome:

• der Start faellt noch vor Beginn der Release-Pipeline fehl
• Fehler betreffen Config-Imports oder das Bundling

Was du prüfen solltest:

• sicherstellen, dass die Config-Datei einen unterstützten Namen hat
• defineConfig aus @pubm/core importieren
• schwere Laufzeit-Arbeit aus dem Top-Level des Config-Moduls entfernen
• prüfen, ob optionale Abhängigkeiten dort installiert sind, wo sie gebraucht werden

Gute Config-Dateien sind vor allem deklarativ. Wenn die Datei wie Anwendungs-Code aussieht, lagere Hilfsfunktionen in kleinere Module aus und halte die Auswertung vorhersehbar.

npm-Publish scheitert mit Auth- oder Berechtigungsfehlern

Symptome:

• 401- oder 403-Antworten
• Meldungen zu OTP, 2FA oder Publish-Berechtigungen

Was du prüfen solltest:

• NODE_AUTH_TOKEN kontrollieren
• bestaetigen, dass der Token Publish-Zugriff auf das Paket hat
• in CI lieber Automation-kompatible Tokens verwenden
• bestaetigen, dass das Access-Level des Pakets zu den Registry-Erwartungen passt

Wenn das Repository scoped Public Packages veröffentlicht, auch prüfen, ob das Paket auf npm oeffentlich sein soll.

jsr-Publish scheitert

Symptome:

• das jsr-Ziel scheitert, während npm funktioniert

Was du prüfen solltest:

• JSR_TOKEN kontrollieren
• pubm --mode ci --phase prepare ausführen
• bestaetigen, dass die Paketmetadaten für jsr gueltig sind

Weil pubm an mehrere Ziele veröffentlicht, solltest du die fehlerhafte Registry reparieren, statt blind erneut zu versuchen und damit mögliche Teilveröffentlichungen zu verwechseln.

crates.io-Publish scheitert

Symptome:

• Rust-Paketveröffentlichung scheitert
• ein Crate klappt, blockiert aber ein anderes in der Sequenz

Was du prüfen solltest:

• CARGO_REGISTRY_TOKEN kontrollieren
• bestaetigen, dass Abhängigkeitsreihenfolge und Versionen der Crates gueltig sind
• die paketbezogene registries-Überschreibung in pubm.config.* prüfen (oder Manifest-Dateien, falls Ableitung genutzt wird)

Rust-Publishes werden sequentiell ausgeführt, wenn die Reihenfolge wichtig ist. Das ist normal und meist ein Zeichen dafür, dass pubm die Abhängigkeitskonsistenz schuetzt.

Build- oder Test-Schritt scheitert innerhalb von pubm

Symptome:

• der Release-Flow stoppt während Test oder Build
• die Fehlermeldung empfiehlt, das zugrunde liegende Script erneut auszufuehren

Was du tun solltest:

1. das Script direkt erneut ausführen
2. den eigentlichen Build- oder Testfehler beheben
3. pubm erneut starten

Beispiele:

pnpm run test
pnpm run build

Wenn deine Scripts andere Namen haben, gleiche sie mit Config oder CLI-Flags ab:

pubm --test-script test:ci --build-script build:release

Veröffentlichung aus contents funktioniert nicht

Symptome:

• der Publish-Befehl findet erwartete Dateien nicht
• Release funktioniert aus dem Root, scheitert aber aus dist/

Was du prüfen solltest:

• bestaetigen, dass contents auf das finale Publish-Verzeichnis zeigt
• sicherstellen, dass der Build-Schritt dieses Verzeichnis erzeugt, bevor der Publish beginnt
• prüfen, ob das Zielverzeichnis die Manifest-Dateien enthaelt, die die gewaehlte Registry erwartet (package.json für npm, jsr.json oder deno.json / deno.jsonc für jsr, Cargo.toml für crates)

contents ändert das Working Directory für die Laufzeit-Pipeline. Behandle es als Publish-Root, nicht nur als Ausgabeverzeichnis.

CI funktioniert anders als lokale Laeufe

Symptome:

• lokales Veröffentlichen klappt
• CI-Publish scheitert oder haengt

Warum das passiert:

• CI deaktiviert Prompts
• Tokens muessen aus Umgebungsvariablen oder vorheriger Secret-Synchronisierung kommen
• flache Checkouts brechen häufig tag-bewusste Flows

Was du prüfen solltest:

• pubm --mode ci --phase prepare lokal ausführen
• in CI den vollen Git-Verlauf verwenden
• bestaetigen, dass jedes erforderliche Token in der Job-Umgebung vorhanden ist

Probleme mit GitHub Releases

Symptome:

• die Erstellung des Releases scheitert
• die Release-Metadaten wirken unvollständig

Was du prüfen solltest:

• bestaetigen, dass die Remote-Metadaten des Repositories gueltig sind
• sicherstellen, dass Git-Tags existieren und gepusht wurden
• zwischen normalem Publish-Flow und --mode ci --phase publish unterscheiden

pubm erstellt einen GitHub Release über die API. Ohne GITHUB_TOKEN im lokalen Modus kannst du einen Token eingeben, einen Draft im Browser oeffnen oder ueberspringen. --mode ci --phase publish erstellt im Rahmen der Pipeline einen GitHub Release über die API.

Rollback ist passiert und der Repository-Zustand wirkt verwirrend

Symptome:

• der Publish schlug mitten im Lauf fehl
• Tags oder Commits wurden erstellt und anschliessend entfernt

Was du tun solltest:

• aktuelle Tags mit git tag ansehen
• Working-Tree-Status mit git status ansehen
• erst erneut laufen lassen, wenn du verstanden hast, welcher Schritt zuerst fehlgeschlagen ist

Wichtig ist, die urspruengliche Ursache zu diagnostizieren, nicht die Rollback-Meldungen, die danach kommen.

Versionsnummer nach Rollback-Unpublish verbraucht

Symptome:

• der Publish schlug fehl, der Rollback lief durch und hat ein Paket von npm unpublisht oder von crates.io geyankt
• ein erneuter Publish mit derselben Version schlaegt fehl, weil die Version bereits vergeben ist

Was passiert ist:

npm unpublish entfernt den Paket-Tarball, aber die Versionsnummer ist dauerhaft reserviert: sie kann nicht wiederverwendet werden. crates.io cargo yank markiert die Version ebenfalls als nicht mehr verwendbar.

Was zu tun ist:

• auf eine neue Version hochsetzen (z. B. 1.2.4 statt 1.2.3) und erneut veröffentlichen
• in CI wird Unpublish standardmaessig uebersprungen, um Versionsnummern nicht zu verbrauchen: aktiviere --dangerously-allow-unpublish oder setze rollback.dangerouslyAllowUnpublish: true in der Config, um es zu erlauben

Wann du ein Issue melden solltest

Erstelle ein Issue, wenn du das Problem reproduzieren kannst mit:

• dem exakten Befehl
• relevanter Config
• Ziel-Registries
• erwartetem Verhalten
• tatsaechlichem Verhalten und Fehlerausgabe

Besonders wertvoll sind hochwertige Bug-Reports fuer:

• gemischte JS- und Rust-Repositories
• von Plugins bereitgestellte Registries
• Sonderfaelle des Config-Loaders
• Rollback-Verhalten nach teilweisen Fehlern

Nuetzlicher Recovery-Workflow

Wenn ein Release fehlgeschlagen ist und du konservativ wiederherstellen willst:

git status
git tag --sort=-creatordate | head
pubm changesets status --verbose
pubm changesets version --dry-run
pubm --dry-run
pubm --mode ci --phase prepare

Fuehre einen echten Publish erst dann wieder aus, wenn die Ausgaben des Dry-Runs und der CI-Vorbereitung wieder sinnvoll aussehen.