Fehlerbehebung

Jeder Eintrag geht von dem aus, was du siehst, und verlinkt den Code dahinter mit Fehlercodes, wo jeder Code mit Bedeutung, Exit-Code und nächstem Schritt steht. Such nach dem Code in verbatra: error [CODE], nie nach dem Meldungstext.

Führe verbatra doctor aus, bevor du Eintrag für Eintrag durchgehst: Es prüft Konfiguration, Format, Provider, die Variable des API-Schlüssels und die Quelldatei in einem Durchgang, kostet nichts und funktioniert schon, bevor die Quell-Locale-Datei existiert.

pnpm blockiert die Installationsskripte einer Abhängigkeit (ERR_PNPM_IGNORED_BUILDS)Link zu diesem Abschnitt kopieren

Symptom: pnpm add -D @verbatra/cli gibt seine Installationszusammenfassung aus und beendet sich dann mit 1:

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @google/genai@3.1.0, protobufjs@7.6.5
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

pnpm schreibt außerdem eine pnpm-workspace.yaml in dein Projekt, die eine unbeantwortete Entscheidung enthält:

allowBuilds:
  '@google/genai': set this to true or false
  protobufjs: set this to true or false

Solange du sie nicht beantwortest, scheitert jeder spätere pnpm-Befehl in diesem Projekt auf dieselbe Weise, auch pnpm exec verbatra init.

Ursache: pnpm führt die Installationsskripte einer Drittanbieter-Abhängigkeit nur aus, wenn du es erlaubst. @google/genai und das transitive protobufjs deklarieren solche Skripte, und das Gemini-SDK wird unabhängig vom konfigurierten Provider installiert, also trifft es jeden pnpm-Installationsweg. verbatra selbst deklariert kein Installationsskript, und npm und yarn installieren dasselbe Paket ohne Nachfrage. Die Installation ist tatsächlich durchgelaufen: node_modules/.bin/verbatra funktioniert bereits.

Lösung: Beantworte die Entscheidung einmal. Interaktiv führst du pnpm approve-builds aus und bestätigst keinen der beiden Einträge. Nicht-interaktiv, was du in CI willst, hinterlegst du die Antwort vor der Installation, indem du das hier in die pnpm-workspace.yaml im Wurzelverzeichnis des Projekts schreibst:

allowBuilds:
  '@google/genai': false
  protobufjs: false

verbatra braucht diese Skripte nicht, und dieses Repository lehnt beide ab. Mit der hinterlegten Antwort beendet sich pnpm add -D @verbatra/cli mit 0 und spätere pnpm-Befehle laufen normal. Die Paketversionen in der Meldung folgen dem Release; die Lösung bleibt dieselbe.

Die Konfiguration ist ungültig (CONFIG_INVALID)Link zu diesem Abschnitt kopieren

Symptom: The verbatra configuration is invalid: ..., mit einem Problem pro Feld.

Ursache: Die Konfiguration wurde gefunden, besteht aber die Prüfung nicht, zum Beispiel ein files.pattern ohne {locale}, ein Locale-Code, der kein BCP 47 ist (etwa en_US), oder ein unbekannter Key. Ein unbekannter Key bekommt den Hinweis API keys are read from the environment, not the config: Das Schema ist streng, damit sich kein Secret in einer committeten Datei verstecken kann.

Lösung: Korrigiere das Feld, das die Meldung nennt; siehe Die Konfigurationsdatei. Bei No verbatra configuration found... siehe CONFIG_NOT_FOUND. Code: CONFIG_INVALID.

Kein Adapter für das Format (UNKNOWN_FORMAT)Link zu diesem Abschnitt kopieren

Symptom: No adapter is registered for format "...", gefolgt von der Liste der unterstützten Formate.

Ursache: Das format der Konfiguration ist keine registrierte ID. Ein custom:-Format läuft nicht auf der Kommandozeile, denn sie lädt kein Plugin.

Lösung: Nimm eine ID aus Formate. Für ein custom:-Format arbeite über das SDK mit einer Registry, die seinen Adapter enthält: siehe Einen eigenen Format-Adapter schreiben. Code: UNKNOWN_FORMAT.

Die angeforderte Locale ist nicht konfiguriert (UNKNOWN_LOCALE)Link zu diesem Abschnitt kopieren

Symptom: Requested locale not in the configured target locales: ...

Ursache: --locales (oder eine locales-Eingabe im SDK) nennt eine Locale, die nicht in targetLocales steht. Ein Filter wählt aus der konfigurierten Liste aus; er ergänzt sie nie.

Lösung: Nimm die Locale in targetLocales auf, oder korrigiere den Tippfehler. Code: UNKNOWN_LOCALE.

Die Quelldatei fehlt oder lässt sich nicht parsen (SOURCE_UNREADABLE, SOURCE_INVALID)Link zu diesem Abschnitt kopieren

Symptom: The source locale file was not found at <path>. oder The source locale file at <path> could not be read: ...

Ursache: files.pattern mit eingesetztem Quell-Locale zeigt auf keine Datei, oder die Datei lässt sich nicht parsen. Der Pfad wird gegen die Projektwurzel aufgelöst, das Verzeichnis der gefundenen Konfiguration (oder mit --config das Arbeitsverzeichnis), also ist ein falsches --cwd oder --config eine häufige Ursache, ebenso ein Platzhalter: files.pattern ist ein wörtlicher Pfad, kein Glob (siehe Namespace-Layouts).

Lösung: Prüf den ausgegebenen Pfad. Bei einem Parse-Fehler nennt der causeCode den Code des Format-Adapters. Codes: SOURCE_UNREADABLE, SOURCE_INVALID.

Fehlender API-Schlüssel (PROVIDER_CONSTRUCTION_FAILED)Link zu diesem Abschnitt kopieren

Symptom: Failed to construct provider "anthropic": The ANTHROPIC_API_KEY environment variable is not set. (oder die Variable deines Providers).

Ursache: Die Variable, die die Meldung nennt, ist nicht gesetzt oder leer. Schlüssel kommen nur aus der Umgebung, nie aus der Konfiguration oder einem Flag.

Lösung: Setz die Variable und bestätige sie mit verbatra doctor. Die CLI liest sie auch aus .env.local und .env; das SDK nicht, also nutze in deinem eigenen Skript node --env-file=.env. Codes: PROVIDER_CONSTRUCTION_FAILED, MISSING_API_KEY.

Rate-Limits, Timeouts und Auth-Fehlschläge mitten im Lauf (RATE_LIMITED, TIMEOUT, AUTH_FAILED)Link zu diesem Abschnitt kopieren

Symptom: Der Lauf wird fertig, aber einige Keys stehen unter providerFailures mit einem Hinweis SUB_BATCH_FAILED, der den Provider-Code nennt, und der Befehl endet mit 1.

Ursache: Eine Provider-Anfrage ist gescheitert, nachdem der Provider gebaut war: HTTP 429, ein Timeout oder HTTP 401/403.

Lösung: Nichts geht verloren; die Keys werden beim nächsten Lauf wieder aufgegriffen. Starte bei RATE_LIMITED später erneut, nach der Wartezeit, die die Meldung nennt, falls sie eine nennt (ein erschöpftes Tageskontingent), und bei einem strengen Kontingent eine Locale nach der anderen mit --locales. Für ein langsames Modell heb gegen TIMEOUT den Wert requestTimeoutMs an. AUTH_FAILED löst sich nicht durch Wiederholen: Ersetze den Schlüssel.

Die Lock-Datei ist beschädigt (LOCK_FILE_INVALID)Link zu diesem Abschnitt kopieren

Symptom: The lock-file at <path> is not valid JSON., ... has an unexpected shape., ... has version N ... oder ... exceeds the maximum allowed size ...

Ursache: verbatra.lock.json wurde von Hand bearbeitet, abgeschnitten, bei einem Merge beschädigt oder von einer inkompatiblen Version geschrieben. translate und import brechen daran den ganzen Lauf ab, und Locales, die vor dem Abbruch fertig waren, behalten, was sie geschrieben haben.

Lösung: Stell die Datei aus der Versionskontrolle wieder her. Sie zu löschen beseitigt den Fehler auch, verliert aber die Baselines, sodass frühere Änderungen an der Quelle nicht mehr als veraltet erkannt werden. Siehe Die Lock-Datei. Code: LOCK_FILE_INVALID.

Eine Locale-Datei konnte nicht geschrieben werden (TARGET_UNWRITABLE)Link zu diesem Abschnitt kopieren

Symptom: Eine Locale scheitert mit Could not write the locale file locales/de.json (EACCES). ...

Ursache: Die Datei oder ihr Verzeichnis ist nicht beschreibbar: Rechte, ein fehlendes Verzeichnis, ein schreibgeschützter Mount oder eine volle Platte. Geschrieben wird über eine temporäre Datei im selben Verzeichnis, also muss auch das Verzeichnis beschreibbar sein.

Lösung: Behebe, was der Dateisystem-Code nennt, und starte erneut. Nur diese Locale scheitert, und sie behält ihre vorige Datei und Baseline. Code: TARGET_UNWRITABLE.

Ein anderer Prozess hält die Schreibsperre (LOCK_CONTENDED)Link zu diesem Abschnitt kopieren

Symptom: Could not acquire the write lock at <path>: another process is holding it. ...

Ursache: Ein anderes translate, watch, import oder ein Schreibvorgang aus Studio hält die Sperre der Locale. Eine Sperre eines beendeten Prozesses auf diesem Rechner wird automatisch zurückgeholt, eine verbliebene stammt also von einem anderen Rechner oder einem verbatra älter als 0.12.0.

Lösung: Warte auf den anderen Lauf, oder lösch die ausgegebene Sperrdatei, wenn nirgends ein verbatra-Prozess läuft. --lock-timeout <seconds> bei translate, watch und import ändert, wie lange ein Lauf wartet. Code: LOCK_CONTENDED.

Gepunktete Keys oder YAML-Keys kollidieren (INVALID_STRUCTURE)Link zu diesem Abschnitt kopieren

Symptom: A dotted key and a nested key path resolve to the same path. oder bei YAML A mapping key is a map or sequence (expected scalar keys).

Ursache: Zwei Einträge einer Datei laufen auf denselben Key hinaus, etwa "a.b" neben a: { b: ... }, oder ein YAML-Key hat keine String-Form. verbatra lehnt ab, statt einen zu verwerfen.

Lösung: Benenne einen der Keys um, oder nimm einen skalaren YAML-Key. In der Quelldatei kommt das in SOURCE_INVALID eingepackt an. Code: INVALID_STRUCTURE.

Der Lauf hat einige Keys ausgelassen (Token-Budget)Link zu diesem Abschnitt kopieren

Symptom: ein Hinweis BUDGET_TOKENS_EXCEEDED; unter budgetBehavior: "stop" stehen außerdem Keys unter budgetWithheld.

Ursache: Der Lauf hat maxTokens aus der Konfiguration oder --max-tokens für den Lauf erreicht. "warn" meldet nur ein Budget aus der Konfiguration; "stop" und --max-tokens, egal was die Konfiguration sagt, halten jeden noch nicht versuchten Key zurück, und das Locale endet partial oder failed.

Lösung: Das ist die Leitplanke bei der Arbeit: Was angekommen ist, ist geschrieben, und zurückgehaltene Keys werden beim nächsten Lauf übersetzt. Heb das Budget an oder wechsle zu "warn", wenn ein Lauf alles schaffen soll. Wie das Budget zählt, steht in Übersetzungssicherheit. Code: BUDGET_TOKENS_EXCEEDED.

Eine Übersetzung wird wegen Inline-Markup zurückgehalten (Integritätsabweichung)Link zu diesem Abschnitt kopieren

Symptom: Ein Key steht unter integrityMismatches und behält seinen vorigen Wert, oder Studio zeigt Rejected: inline markup mismatch mit den schuldigen Tags: -<a href> für ein Tag, das der Kandidat verloren hat, +<i> für eines, das er erfunden hat. verbatra check --qa meldet dasselbe für Werte, die schon auf der Platte liegen.

Ursache: Der Kandidat trägt die Inline-Tags der Quelle nicht, oder er trägt sie unausgeglichen oder falsch verschachtelt, also lehnt das Integritäts-Gate ihn ab wie einen verlorenen Platzhalter.

Lösung: Lass den Key erneut laufen, oder korrigiere den Wert von Hand in Studio oder einer Arbeitsmappe; dasselbe Gate beurteilt beides. Was verglichen wird und welche Ablehnungen gewollt sind, steht unter Inline-Markup-Parität.

Studio: Der Port ist schon belegtLink zu diesem Abschnitt kopieren

Symptom: port 5849 is already in use (oder dein --port-Wert).

Ursache: Ein anderer Prozess, oft ein früheres Studio, belegt den Port.

Lösung: Beende ihn, oder starte Studio auf einem anderen Port: verbatra studio --port 6000.

Studio: @verbatra/studio ist nicht installiertLink zu diesem Abschnitt kopieren

Symptom: Verbatra Studio requires @verbatra/studio., gefolgt von den Installationsbefehlen.

Ursache: Studio ist ein eigenes Paket, das der Befehl studio bei Bedarf lädt.

Lösung: npm install --save-dev @verbatra/studio, oder für einen einmaligen Lauf npx -y -p @verbatra/cli -p @verbatra/studio verbatra studio. Mit pnpm lies vorher pnpm blockiert die Installationsskripte einer Abhängigkeit.

npx @verbatra/cli startet die CLI, die im Paket des aktuellen Ordners installiert ist, also führe es im Projektstamm aus (oder nutze pnpm exec verbatra in einem Workspace-Unterpaket); anderswo lädt npx die neueste CLI, die vielleicht nicht zu deinem lokalen @verbatra/studio oder @verbatra/mcp passt.

Studio: Retranslate- und Translate-Aktionen fehlenLink zu diesem Abschnitt kopieren

Symptom: Bearbeiten funktioniert, aber die Aktionen zum Neuübersetzen und zum Übersetzen offener Keys erscheinen nicht.

Ursache: Ausgaben beim Provider werden beim Start erlaubt, nach den Regeln unter Ausgaben und Agent-Tools, und ohne diese Erlaubnis werden die Ausgabe-Aktionen nicht registriert.

Lösung: Starte neu mit verbatra studio --allow-spend, außer das Projekt ist nur mit Menschen. Siehe Review in Studio.

MCP: @verbatra/mcp ist nicht installiertLink zu diesem Abschnitt kopieren

Symptom: Verbatra's MCP server requires @verbatra/mcp., gefolgt von den Installationsbefehlen.

Ursache: Der MCP-Server ist ein eigenes Paket, das der Befehl mcp bei Bedarf lädt, also funktioniert npx -y @verbatra/cli mcp allein nie.

Lösung: Führe npx -y @verbatra/mcp aus, oder installiere @verbatra/mcp neben der CLI und starte verbatra mcp erneut. Mit pnpm lies vorher pnpm blockiert die Installationsskripte einer Abhängigkeit.

MCP: tools/list eines Agenten zeigt nie translation.retranslateEntry oder translation.translatePendingLink zu diesem Abschnitt kopieren

Symptom: Die lokalen Tools funktionieren, aber die beiden Ausgabe-Tools fehlen, und ein Aufruf per Name scheitert als unbekanntes Tool.

Ursache: Ausgaben werden beim Start erlaubt, nach den Regeln unter Kostenpflichtige Tools, und die Tool-Liste darf sich nicht pro Verbindung ändern, also bleiben die Ausgabe-Tools ganz draußen.

Lösung: Starte neu mit verbatra mcp --allow-spend, außer das Projekt ist nur mit Menschen.

Einen Lauf rückgängig machen (kein Fehlercode)Link zu diesem Abschnitt kopieren

verbatra hat keinen Befehl zum Rückgängigmachen; die Versionskontrolle ist der Weg zurück. Setz die Locale-Dateien, verbatra.lock.json und verbatra.provenance.json gemeinsam zurück, nie die Locale-Dateien allein. Siehe Wiederherstellung und Rollback.