---
title: "Fehlerbehebung"
description: "Symptome, Ursachen und Lösungen für die Fehler, die verbatra tatsächlich erzeugt, jeweils unter ihrem Fehlercode, dazu Installationsprobleme mit Studio und MCP."
type: "reference"
---
# Fehlerbehebung

Symptome, Ursachen und Lösungen für die Fehler, die verbatra tatsächlich erzeugt, jeweils unter ihrem Fehlercode, dazu Installationsprobleme mit Studio und MCP.

Jeder Eintrag geht von dem aus, was du siehst, und verlinkt den Code dahinter mit
[Fehlercodes](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md), 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`](https://verbatra.kreitz-webdev.de/de/docs/cli/doctor.md) 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) [#pnpm-blockiert-die-installationsskripte-einer-abhängigkeit-err_pnpm_ignored_builds]

**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:

```yaml
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:

```yaml
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) [#die-konfiguration-ist-ungültig-config_invalid]

**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](https://verbatra.kreitz-webdev.de/de/docs/config-file.md).
Bei `No verbatra configuration found...` siehe [`CONFIG_NOT_FOUND`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#config_not_found).
Code: [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#config_invalid).

## Kein Adapter für das Format (UNKNOWN_FORMAT) [#kein-adapter-für-das-format-unknown_format]

**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](https://verbatra.kreitz-webdev.de/de/docs/formats.md). Für ein `custom:`-Format arbeite über das
SDK mit einer Registry, die seinen Adapter enthält: siehe
[Einen eigenen Format-Adapter schreiben](https://verbatra.kreitz-webdev.de/de/docs/custom-format-adapters.md). Code:
[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format).

## Die angeforderte Locale ist nicht konfiguriert (UNKNOWN_LOCALE) [#die-angeforderte-locale-ist-nicht-konfiguriert-unknown_locale]

**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`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale).

## Die Quelldatei fehlt oder lässt sich nicht parsen (SOURCE_UNREADABLE, SOURCE_INVALID) [#die-quelldatei-fehlt-oder-lässt-sich-nicht-parsen-source_unreadable-source_invalid]

**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](https://verbatra.kreitz-webdev.de/de/docs/formats.md#namespace-layouts)).

**Lösung**: Prüf den ausgegebenen Pfad. Bei einem Parse-Fehler nennt der `causeCode` den
[Code des Format-Adapters](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#adapter-error-codes). Codes:
[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_unreadable),
[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_invalid).

## Fehlender API-Schlüssel (PROVIDER_CONSTRUCTION_FAILED) [#fehlender-api-schlüssel-provider_construction_failed]

**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`](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien); das SDK nicht, also nutze in deinem
eigenen Skript `node --env-file=.env`. Codes:
[`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provider_construction_failed),
[`MISSING_API_KEY`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#missing_api_key).

## Rate-Limits, Timeouts und Auth-Fehlschläge mitten im Lauf (RATE_LIMITED, TIMEOUT, AUTH_FAILED) [#rate-limits-timeouts-und-auth-fehlschläge-mitten-im-lauf-rate_limited-timeout-auth_failed]

**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`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#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`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#timeout) den Wert [`requestTimeoutMs`](https://verbatra.kreitz-webdev.de/de/docs/providers.md#anfrage-timeout)
an. [`AUTH_FAILED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#auth_failed) löst sich nicht durch Wiederholen: Ersetze den
Schlüssel.

## Die Lock-Datei ist beschädigt (LOCK_FILE_INVALID) [#die-lock-datei-ist-beschädigt-lock_file_invalid]

**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](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md). Code:
[`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_file_invalid).

## Eine Locale-Datei konnte nicht geschrieben werden (TARGET_UNWRITABLE) [#eine-locale-datei-konnte-nicht-geschrieben-werden-target_unwritable]

**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`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#target_unwritable).

## Ein anderer Prozess hält die Schreibsperre (LOCK_CONTENDED) [#ein-anderer-prozess-hält-die-schreibsperre-lock_contended]

**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`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md),
[`watch`](https://verbatra.kreitz-webdev.de/de/docs/cli/watch.md) und [`import`](https://verbatra.kreitz-webdev.de/de/docs/cli/import.md) ändert, wie lange ein Lauf wartet.
Code: [`LOCK_CONTENDED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_contended).

## Gepunktete Keys oder YAML-Keys kollidieren (INVALID_STRUCTURE) [#gepunktete-keys-oder-yaml-keys-kollidieren-invalid_structure]

**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`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#invalid_structure).

## Der Lauf hat einige Keys ausgelassen (Token-Budget) [#der-lauf-hat-einige-keys-ausgelassen-token-budget]

**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](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#das-token-budget). Code:
[`BUDGET_TOKENS_EXCEEDED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#budget_tokens_exceeded).

## Eine Übersetzung wird wegen Inline-Markup zurückgehalten (Integritätsabweichung) [#eine-übersetzung-wird-wegen-inline-markup-zurückgehalten-integritätsabweichung]

**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](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#inline-markup-parität).

## Studio: Der Port ist schon belegt [#studio-der-port-ist-schon-belegt]

**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 installiert [#studio-verbatrastudio-ist-nicht-installiert]

**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](#pnpm-blockiert-die-installationsskripte-einer-abhängigkeit-err_pnpm_ignored_builds).

`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 fehlen [#studio-retranslate--und-translate-aktionen-fehlen]

**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](https://verbatra.kreitz-webdev.de/de/docs/cli/studio.md#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](https://verbatra.kreitz-webdev.de/de/docs/human-only-workflow.md). Siehe [Review in Studio](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md).

## MCP: @verbatra/mcp ist nicht installiert [#mcp-verbatramcp-ist-nicht-installiert]

**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](#pnpm-blockiert-die-installationsskripte-einer-abhängigkeit-err_pnpm_ignored_builds).

## MCP: tools/list eines Agenten zeigt nie `translation.retranslateEntry` oder `translation.translatePending` [#mcp-toolslist-eines-agenten-zeigt-nie-translationretranslateentry-oder-translationtranslatepending]

**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](https://verbatra.kreitz-webdev.de/de/docs/cli/mcp.md#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](https://verbatra.kreitz-webdev.de/de/docs/human-only-workflow.md).

## Einen Lauf rückgängig machen (kein Fehlercode) [#einen-lauf-rückgängig-machen-kein-fehlercode]

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](https://verbatra.kreitz-webdev.de/de/docs/recovery-and-rollback.md).