--- title: "Fehlercodes" description: "Jeder Fehler-, Ergebnis- und Hinweiscode, den verbatra meldet: was er bedeutet, welche Befehle ihn auslösen, der Exit-Code und der nächste Schritt." type: "reference" --- # Fehlercodes Jeder Fehler-, Ergebnis- und Hinweiscode, den verbatra meldet: was er bedeutet, welche Befehle ihn auslösen, der Exit-Code und der nächste Schritt. Jeder Fehler, den verbatra meldet, trägt einen stabilen Code: in der Zeile `verbatra: error [CODE] message` auf stderr, als `code` oder `causeCode` eines `--json`-Envelopes, als `error.code` einer gescheiterten Locale oder als Hinweis in der Laufzusammenfassung. Verzweige auf den Code, nie auf die Meldung. Jeder Code hat seinen eigenen Anker, `/docs/error-codes#` gefolgt vom Code in Kleinbuchstaben, etwa [`#config_not_found`](#config_not_found). Der **Nächste Schritt** eines Fehlercodes ist der Hinweis, den verbatra nach der Fehlerzeile als `next: ...` ausgibt und in das Feld `hint` des Envelopes schreibt. Er steht hier genau so, wie verbatra ihn ausgibt, auf Englisch, und das SDK liefert denselben Text aus [`errorHint`](https://verbatra.kreitz-webdev.de/de/docs/sdk/errors.md#errorhint). Die Exit-Codes selbst und die Form des Envelopes stehen auf [Exit-Codes und JSON-Ausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md); Hilfe vom Symptom her findest du unter [Fehlerbehebung](https://verbatra.kreitz-webdev.de/de/docs/troubleshooting.md). Zwei Codes gehören zu zwei Familien: `CONFIG_INVALID` (das SDK und `init` in der CLI) und `NETWORK_POLICY_VIOLATION` (das SDK und die Provider). Der Anker in Kleinbuchstaben führt zum SDK-Eintrag; der andere Eintrag hat einen Anker mit Präfix. ## Code-Index [#code-index] Jeder Fehlercode mit seiner Familie und den Exit-Codes, mit denen er einen CLI-Lauf beenden kann; wann welcher gilt, sagt der Abschnitt seiner Familie. | Code | Familie | Exit-Code | | --- | --- | --- | | [`AGENT_FILE_INVALID`](#agent_file_invalid) | CLI | `2` | | [`CLI_ERROR`](#cli_error) | CLI | `2` | | [`CONFIG_EXISTS`](#config_exists) | CLI | `2` | | [`CONFIG_INVALID`](#cli-config_invalid) | CLI | `2` | | [`FORMAT_AMBIGUOUS`](#format_ambiguous) | CLI | `2` | | [`INIT_UNWRITABLE`](#init_unwritable) | CLI | `2` | | [`INVALID_CONCURRENCY`](#invalid_concurrency) | CLI | `2` | | [`INVALID_DEBOUNCE`](#invalid_debounce) | CLI | `2` | | [`INVALID_DIRECTION`](#invalid_direction) | CLI | `2` | | [`INVALID_FORMAT`](#invalid_format) | CLI | `2` | | [`INVALID_LOCALE`](#invalid_locale) | CLI | `2` | | [`INVALID_LOCALES`](#invalid_locales) | CLI | `2` | | [`INVALID_LOCK_TIMEOUT`](#invalid_lock_timeout) | CLI | `2` | | [`INVALID_MAX_TOKENS`](#invalid_max_tokens) | CLI | `2` | | [`INVALID_OPTION`](#invalid_option) | CLI | `2` | | [`INVALID_OUT`](#invalid_out) | CLI | `2` | | [`INVALID_PORT`](#invalid_port) | CLI | `2` | | [`INVALID_PROVIDER`](#invalid_provider) | CLI | `2` | | [`INVALID_QA_OPTION`](#invalid_qa_option) | CLI | `2` | | [`INVALID_SEVERITY`](#invalid_severity) | CLI | `2` | | [`LAYOUT_AMBIGUOUS`](#layout_ambiguous) | CLI | `2` | | [`MISSING_OPTIONS`](#missing_options) | CLI | `2` | | [`REDACTION_UNSUPPORTED`](#redaction_unsupported) | CLI | `2` | | [`USAGE_ERROR`](#usage_error) | CLI | `2` | | [`CONFIG_NOT_FOUND`](#config_not_found) | SDK | `2` oder `1` | | [`CONFIG_INVALID`](#config_invalid) | SDK | `2` oder `1` | | [`UNKNOWN_FORMAT`](#unknown_format) | SDK | `2` oder `1` | | [`UNKNOWN_LOCALE`](#unknown_locale) | SDK | `2` | | [`UNKNOWN_KEY`](#unknown_key) | SDK | keiner | | [`KEY_PROTECTED`](#key_protected) | SDK | keiner | | [`KEY_PINNED`](#key_pinned) | SDK | keiner | | [`PROVIDER_CONSTRUCTION_FAILED`](#provider_construction_failed) | SDK | `2` | | [`MACHINE_TRANSLATION_DISABLED`](#machine_translation_disabled) | SDK | keiner | | [`NETWORK_POLICY_VIOLATION`](#network_policy_violation) | SDK | `2` | | [`SOURCE_UNREADABLE`](#source_unreadable) | SDK | `2` oder `1` | | [`SOURCE_INVALID`](#source_invalid) | SDK | `2` oder `1` | | [`LOCK_FILE_INVALID`](#lock_file_invalid) | SDK | `2` | | [`PROVENANCE_FILE_INVALID`](#provenance_file_invalid) | SDK | `2` | | [`PROVENANCE_FILE_UNWRITABLE`](#provenance_file_unwritable) | SDK | keiner | | [`REVIEW_VALUE_CHANGED`](#review_value_changed) | SDK | keiner | | [`REVIEW_SOURCE_CHANGED`](#review_source_changed) | SDK | keiner | | [`REVIEW_REJECT_UNSUPPORTED`](#review_reject_unsupported) | SDK | keiner | | [`REVIEW_RESTORE_FAILED`](#review_restore_failed) | SDK | keiner | | [`REVIEWER_INVALID`](#reviewer_invalid) | SDK | `2` | | [`LOCK_CONTENDED`](#lock_contended) | SDK | `1` | | [`GLOSSARY_NOT_FILE_BACKED`](#glossary_not_file_backed) | SDK | keiner | | [`GLOSSARY_UNWRITABLE`](#glossary_unwritable) | SDK | keiner | | [`LOCALE_LAYOUT_INVALID`](#locale_layout_invalid) | SDK | `2` | | [`LOCALE_PATH_COLLISION`](#locale_path_collision) | SDK | `2` | | [`CONCURRENCY_INVALID`](#concurrency_invalid) | SDK | keiner | | [`CONCURRENCY_BUDGET_CONFLICT`](#concurrency_budget_conflict) | SDK | `2` | | [`MAX_TOKENS_INVALID`](#max_tokens_invalid) | SDK | keiner | | [`LOCK_TIMEOUT_INVALID`](#lock_timeout_invalid) | SDK | keiner | | [`PAGE_CURSOR_INVALID`](#page_cursor_invalid) | SDK | keiner | | [`PAGE_LIMIT_INVALID`](#page_limit_invalid) | SDK | keiner | | [`TARGET_UNWRITABLE`](#target_unwritable) | SDK | `1` oder `2` | | [`PSEUDO_OUTPUT_CONFLICT`](#pseudo_output_conflict) | SDK | `2` | | [`SOURCE_UNWRITABLE`](#source_unwritable) | SDK | `2` | | [`EXTRACT_NOT_CONFIGURED`](#extract_not_configured) | SDK | `2` | | [`EXTRACT_FS_UNSUPPORTED`](#extract_fs_unsupported) | SDK | keiner | | [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict) | SDK | `2` | | [`TYPES_UNWRITABLE`](#types_unwritable) | SDK | `2` | | [`TMX_OUTPUT_CONFLICT`](#tmx_output_conflict) | SDK | `2` | | [`TMX_UNWRITABLE`](#tmx_unwritable) | SDK | `2` | | [`MEMORY_UNWRITABLE`](#memory_unwritable) | SDK | `2` | | [`EXPORT_OUTPUT_CONFLICT`](#export_output_conflict) | SDK | `2` | | [`EXPORT_UNWRITABLE`](#export_unwritable) | SDK | `2` | | [`LOCALE_STATE_NOT_CARRIED_OVER`](#locale_state_not_carried_over) | SDK | `1` | | [`LOCALE_UNSUPPORTED_BY_PROVIDER`](#locale_unsupported_by_provider) | SDK | `2` | | [`NOT_A_LOCALE_FILE`](#not_a_locale_file) | SDK | `2` | | [`SENSITIVE_CONTENT_WITHHELD`](#sensitive_content_withheld) | SDK | keiner | | [`RUN_CANCELLED`](#run_cancelled) | SDK | keiner | | [`LOCALE_FAILED`](#locale_failed) | SDK | `1` | | [`MISSING_API_KEY`](#missing_api_key) | Provider | `2` | | [`INVALID_REQUEST`](#invalid_request) | Provider | `1` | | [`INVALID_RESPONSE`](#invalid_response) | Provider | `1` | | [`OUTPUT_TRUNCATED`](#output_truncated) | Provider | `1` | | [`PROVIDER_REFUSED`](#provider_refused) | Provider | `1` | | [`PROVIDER_BLOCKED`](#provider_blocked) | Provider | `1` | | [`RATE_LIMITED`](#rate_limited) | Provider | `1` | | [`TIMEOUT`](#timeout) | Provider | `1` | | [`AUTH_FAILED`](#auth_failed) | Provider | `1` | | [`PROVIDER_UNAVAILABLE`](#provider_unavailable) | Provider | `1` | | [`NETWORK_POLICY_VIOLATION`](#provider-network_policy_violation) | Provider | `1` | | [`PROVIDER_ERROR`](#provider_error) | Provider | `1` | | [`INVALID_JSON`](#invalid_json) | Formatadapter | `1` oder `2` | | [`INVALID_YAML`](#invalid_yaml) | Formatadapter | `1` oder `2` | | [`INVALID_XML`](#invalid_xml) | Formatadapter | `1` oder `2` | | [`INVALID_STRUCTURE`](#invalid_structure) | Formatadapter | `1` oder `2` | | [`MAX_DEPTH_EXCEEDED`](#max_depth_exceeded) | Formatadapter | `1` oder `2` | | [`INPUT_TOO_LARGE`](#input_too_large) | Formatadapter | `1` oder `2` | | [`MIXED_STRUCTURE`](#mixed_structure) | Formatadapter | `1` oder `2` | | [`ADAPTER_FAILED`](#adapter_failed) | Formatadapter | keiner | | [`DUPLICATE_FORMAT`](#duplicate_format) | Formatadapter | keiner | | [`INVALID_FORMAT_ID`](#invalid_format_id) | Formatadapter | keiner | ## CLI-Fehlercodes [#cli-error-codes] Diese Codes löst die CLI selbst aus. Dieselbe Liste wird als `CLI_ERROR_CODES` (mit dem Typ `CliErrorCode`) aus `@verbatra/cli` ausgeliefert. Jeder von ihnen endet mit Exit-Code `2`. ### AGENT_FILE_INVALID [#agent_file_invalid] `init --agent` eine Client-Konfiguration (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` oder `.gemini/settings.json`) gefunden hat, die kein reines JSON ist, kein Objekt ist oder einen Server-Wert enthält, der kein Objekt ist, eine `.codex/config.toml`, die es nicht sicher lesen kann oder die den verbatra-Server inline, mit gepunkteten Schlüsseln, als Array von Tabellen oder doppelt setzt, einen symbolischen Link auf einem Pfad, den es schreiben würde, oder eine unpaarige oder doppelte verbatra-Markierung in `AGENTS.md` oder `CLAUDE.md`; es wurde nichts geschrieben. - **Ausgelöst von**: `init --agent` - **Nächster Schritt**: Repair the MCP config or the verbatra markers in the file the message names, or replace the symbolic link it names with a plain file, then run `verbatra init --agent` again. ### CLI_ERROR [#cli_error] Ein Fehlschlag keinen eigenen Code mitbrachte (der Ausweich-Code). - **Ausgelöst von**: jeder Befehl ### CONFIG_EXISTS [#config_exists] `init` ohne `--force` eine abweichende `verbatra.config.ts` überschreiben würde oder eine andere verbatra-Konfigurationsdatei im Verzeichnis zuerst gelesen würde; wird vor jeder fehlenden oder mehrdeutigen Antwort gemeldet, im Terminal schon vor der ersten Frage. - **Ausgelöst von**: `init` - **Nächster Schritt**: Edit the existing config, or pass --force to replace verbatra.config.ts; remove any other config file the message names first. ### CONFIG_INVALID [#cli-config_invalid] `init` aus den erhaltenen Antworten keine gültige Konfiguration erzeugen konnte (das SDK löst denselben Code für eine Konfiguration aus, die sich nicht laden lässt). - **Ausgelöst von**: `init` - **Nächster Schritt**: Correct the init answers the message names, then run `verbatra init` again. ### FORMAT_AMBIGUOUS [#format_ambiguous] `init` mehrere Formate gefunden hat, die die Locale-Dateien lesen; `candidates` listet sie auf. - **Ausgelöst von**: `init` - **Nächster Schritt**: Pass --format with one of the candidates. ### INIT_UNWRITABLE [#init_unwritable] `init` eine Datei nicht in sein Verzeichnis schreiben konnte, etwa weil es schreibgeschützt ist oder eine Datei, die es schreibt, ein symbolischer Link ist, der nicht innerhalb des Projekts aufgelöst wird; die Meldung nennt die Datei, die Ursache und die bereits geschriebenen Dateien. - **Ausgelöst von**: `init` - **Nächster Schritt**: Make the directory writable, or replace the symbolic link the message names with a plain file, then run `verbatra init` again. ### INVALID_CONCURRENCY [#invalid_concurrency] `--concurrency` keine ganze Zahl zwischen 1 und 100 ist. - **Ausgelöst von**: `translate`, `watch` - **Nächster Schritt**: Pass --concurrency as a whole number from 1 to 100. ### INVALID_DEBOUNCE [#invalid_debounce] `watch --debounce` keine ganze Zahl von Millisekunden zwischen 1 und 60000 ist. - **Ausgelöst von**: `watch` - **Nächster Schritt**: Pass --debounce as a whole number of milliseconds from 1 to 60000. ### INVALID_DIRECTION [#invalid_direction] `tmx` eine andere Richtung als `import` oder `export` bekommen hat oder `tmx export` ein Flag nur für den Import (`--dry-run`, `--overwrite`). - **Ausgelöst von**: `tmx` - **Nächster Schritt**: Run `verbatra tmx import` or `verbatra tmx export`, with only the flags that direction takes. ### INVALID_FORMAT [#invalid_format] `--format` bei `export` oder `import` kein unterstütztes Übergabeformat nennt oder `--format` bei `init` kein unterstütztes Format für Locale-Dateien. - **Ausgelöst von**: `export`, `import`, `init` - **Nächster Schritt**: Pass a supported --format value; the command's --help lists them. ### INVALID_LOCALE [#invalid_locale] `pseudo --locale` kein Sprach-Tag aus Buchstaben, Ziffern und Bindestrichen ist oder eine Locale, die bei einer interaktiven `init`-Abfrage eingegeben wurde, kein BCP-47-Code ist (die Flags `--source` und `--targets` scheitern stattdessen mit `CONFIG_INVALID`). - **Ausgelöst von**: `pseudo`, `init` - **Nächster Schritt**: Give the locale as a language tag of letters, digits and hyphens, such as pt-BR or en-XA. ### INVALID_LOCALES [#invalid_locales] `--locales` angegeben wurde, aber keine Locale auflistet, oder die bei einer interaktiven `init`-Abfrage eingegebenen Ziel-Locales die Quell-Locale enthalten. - **Ausgelöst von**: `translate`, `watch`, `check`, `diff`, `export`, `tmx`, `report`, `init` - **Nächster Schritt**: Pass --locales as a comma-separated list of configured target locales, or omit it. ### INVALID_LOCK_TIMEOUT [#invalid_lock_timeout] `--lock-timeout` keine ganze Zahl von Sekunden zwischen 1 und 3600 ist. - **Ausgelöst von**: `translate`, `watch`, `import` - **Nächster Schritt**: Pass --lock-timeout as a whole number of seconds from 1 to 3600. ### INVALID_MAX_TOKENS [#invalid_max_tokens] `translate --max-tokens` keine ganze Zahl von mindestens 1 ist. - **Ausgelöst von**: `translate` - **Nächster Schritt**: Pass --max-tokens as a whole number of at least 1. ### INVALID_OPTION [#invalid_option] Ein `init`-Flag passt nicht zum Provider oder ist fehlerhaft: `--base-url` ohne `openai-compatible` oder `libretranslate`, keine URL oder mit Zugangsdaten, einem Query-String oder einem Fragment; `--api-key-env-var` mit einem anderen Provider als `openai-compatible` oder kein Variablenname; `--model` bei einem Provider ohne Modell (`deepl`, `google-translate`, `libretranslate`, `none`); ein beliebiges Flag mit leerem Wert; `--targets` ohne Locale; `--path` ohne `{locale}`; `--client` ohne `--agent`, ohne Client oder mit einem Client, den init nicht einrichten kann. Oder `--cwd` nennt kein vorhandenes Verzeichnis (bei jedem Befehl, bevor er läuft), `doctor --data-flow` kommt mit `--literals`, `--locales` oder `--live`, `doctor --literals` kommt mit `--locales` oder `--live`, `check --file` nennt keine Datei oder kommt mit `--locales`, `--consistency`, `--require-reviewed` oder `--sensitive`, oder `pseudo --mode` nennt einen anderen Modus als `accented` oder `bidi`. - **Ausgelöst von**: jedem Befehl mit `--cwd`, dazu `init`, `doctor`, `check`, `pseudo` - **Nächster Schritt**: Correct or remove the flag the message names. ### INVALID_OUT [#invalid_out] `--out` bei `types` oder `pseudo` angegeben wurde, aber keinen Pfad nennt. - **Ausgelöst von**: `types`, `pseudo` - **Nächster Schritt**: Pass --out with a file path, or omit it. ### INVALID_PORT [#invalid_port] `studio --port` keine ganze Zahl zwischen 1 und 65535 ist. - **Ausgelöst von**: `studio` - **Nächster Schritt**: Pass --port as a whole number from 1 to 65535. ### INVALID_PROVIDER [#invalid_provider] `init --provider` keinen bekannten Provider nennt. - **Ausgelöst von**: `init` - **Nächster Schritt**: Pass --provider with a supported provider id; `verbatra init --help` lists them. ### INVALID_QA_OPTION [#invalid_qa_option] `check` `--severity` oder `--strict` ohne `--qa` oder `--file` bekommen hat, oder `--strict` zusammen mit `--severity error`. - **Ausgelöst von**: `check` - **Nächster Schritt**: Add --qa or --file, and do not combine --strict with --severity error. ### INVALID_SEVERITY [#invalid_severity] `check --severity` weder `error` noch `warning` ist. - **Ausgelöst von**: `check` - **Nächster Schritt**: Pass --severity error or --severity warning. ### LAYOUT_AMBIGUOUS [#layout_ambiguous] `init` mehrere Dateimuster gefunden hat, die gleich gut passen; `candidates` listet sie auf. - **Ausgelöst von**: `init` - **Nächster Schritt**: Pass --path with one of the candidates. ### MISSING_OPTIONS [#missing_options] `init` nicht fragen konnte (kein Terminal oder `--json`) und ein Wert weder übergeben noch erkannt noch durch `--yes` mit einem Default gefüllt wurde; die Meldung nennt jedes fehlende Flag. - **Ausgelöst von**: `init` - **Nächster Schritt**: Pass the flags the message names, or --yes where the message offers it. ### REDACTION_UNSUPPORTED [#redaction_unsupported] `mcp --redact-values` hat ein älteres `@verbatra/mcp` geladen, das nicht bestätigt, dass es Werte schwärzt; der Server wurde gestoppt, bevor er etwas ausgeliefert hat. - **Ausgelöst von**: `mcp` - **Nächster Schritt**: Upgrade @verbatra/mcp to the version that ships with this CLI, then start `verbatra mcp --redact-values` again. ### USAGE_ERROR [#usage_error] Der Argument-Parser die Befehlszeile abgelehnt hat (eine unbekannte Option, ein fehlendes Argument) oder `mcp` Optionen bekommen hat, die es nicht annehmen kann; sein `hint` nennt das `--help` des Befehls. - **Ausgelöst von**: jeder Befehl - **Nächster Schritt**: Run the command with --help to see the options and arguments it accepts. ## SDK-Fehlercodes [#sdk-error-codes] Fehler, die einen ganzen Lauf betreffen, werfen einen `SdkError` mit einem dieser Codes; [Fehler](https://verbatra.kreitz-webdev.de/de/docs/sdk/errors.md) beschreibt die Klasse und welche Codes ein `cause` tragen. In der CLI beendet ein geworfener Code den Lauf mit `2`, ein Code auf einer einzelnen gescheiterten Locale endet mit `1`. Wo der Index `2` oder `1` nennt, meldet `doctor` den Code als gescheiterte Prüfung und endet mit `1`. Codes ohne CLI-Befehl erreichen dich über das SDK, Studio oder den MCP-Server. ### CONFIG_NOT_FOUND [#config_not_found] Die Suche fand keine Konfiguration, oder ein explizites `configPath` existiert nicht (geworfen von `loadConfig`). - **Ausgelöst von**: jeder Befehl, der die Konfiguration lädt - **Nächster Schritt**: Run `verbatra init` to create a config, or pass the path of an existing config file. ### CONFIG_INVALID [#config_invalid] Eine Konfiguration wurde gefunden, ist aber nicht parsebar oder fällt durch die Validierung, oder ihre Glossardatei konnte nicht aufgelöst werden; `translate` (auch als Dry-Run, außer beim Provider `none`) und `retranslateEntry` werfen ihn außerdem, wenn `VERBATRA_NETWORK_POLICY` oder `VERBATRA_NETWORK_ALLOWED_HOSTS` einen ungültigen Wert enthält, bevor ein Provider gebaut wird. - **Ausgelöst von**: jeder Befehl, der die Konfiguration lädt - **Nächster Schritt**: Fix the config field the message names, then run `verbatra doctor` to confirm the setup. ### UNKNOWN_FORMAT [#unknown_format] Für das konfigurierte Format ist kein Adapter registriert; geworfen, bevor irgendeine Datei gelesen wird. - **Ausgelöst von**: jeder Befehl, der Locale-Dateien liest; Studio und der MCP-Server - **Nächster Schritt**: Set `format` in the config to a supported format, or register an adapter for this one. ### UNKNOWN_LOCALE [#unknown_locale] Eine angefragte Locale gehört nicht zu den konfigurierten Ziel-Locales. - **Ausgelöst von**: `translate`, `watch`, `check`, `diff`, `export`, `tmx`, `report`; Studio und der MCP-Server - **Nächster Schritt**: Use a locale from the config's `targetLocales`, or add it there first. ### UNKNOWN_KEY [#unknown_key] Ein angefragter Key ist nicht in der Quell-Ressource (`keyValue`, `keyIntegrity`, `editEntry`, `retranslateEntry`, `approveEntry`, `rejectEntry`). - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Use a key that exists in the source locale file, or add it there first. ### KEY_PROTECTED [#key_protected] `retranslateEntry` hat es abgelehnt, einen Wert zu ersetzen, den ein Mensch geschrieben, importiert oder außerhalb von verbatra geändert hat, weil weder `includeHuman` noch `humanEdits: "overwrite"` es erlaubt hat. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Keep the human-written value, or opt in to replacing it: include human edits for this call, or set `humanEdits: "overwrite"` in the config. ### KEY_PINNED [#key_pinned] Der Key passt auf die `pinnedKeys` der Konfiguration, also wurde ein maschineller Schreibvorgang abgelehnt (`retranslateEntry` und `editEntry` mit `actor: "agent"`). - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Edit the value by hand, or remove the key from `pinnedKeys` in the config to let verbatra write it. ### PROVIDER_CONSTRUCTION_FAILED [#provider_construction_failed] Der Provider konnte nicht gebaut werden; umhüllt den eigenen Fehler des Providers, einschließlich eines fehlenden API-Keys. Bei einem fehlenden Key nennt der Hinweis statt des nächsten Schritts unten die Variable, etwa `Set GEMINI_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.` Das SDK liest keine `.env`-Datei. - **Ausgelöst von**: `translate`, `watch`; Studio und der MCP-Server - **Nächster Schritt**: Check the config's `provider` block and its API key environment variable, then run `verbatra doctor`. ### MACHINE_TRANSLATION_DISABLED [#machine_translation_disabled] Die Konfiguration setzt `provider: { id: "none" }`, also wurde eine kostenpflichtige Provider-Aktion abgelehnt, bevor ein Provider gebaut wurde (`retranslateEntry`, `assertMachineTranslationEnabled`); `translate` und `watch` werfen ihn nie. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Translate the key by hand, or configure a machine provider in place of `provider: { id: "none" }`. ### NETWORK_POLICY_VIOLATION [#network_policy_violation] Die wirksame [Netzwerkrichtlinie](https://verbatra.kreitz-webdev.de/de/docs/network-policy.md) erlaubt den Endpunkt des Providers oder seinen Proxy nicht; geworfen von `translate` außerhalb eines Probelaufs, von `watch` beim Start und von `retranslateEntry`, bevor der Provider gebaut oder ein API-Key gelesen wird. - **Ausgelöst von**: `translate`, `watch`; Studio und der MCP-Server - **Nächster Schritt**: Point the provider at a host the network policy permits, or add its host to `network.allowedHosts` or VERBATRA_NETWORK_ALLOWED_HOSTS. ### SOURCE_UNREADABLE [#source_unreadable] Die Quell-Locale-Datei existiert nicht, oder bei `import` und `tmx import` die zu importierende Datei bzw. das Verzeichnis. - **Ausgelöst von**: jeder Befehl, der Locale-Dateien liest; Studio und der MCP-Server - **Nächster Schritt**: Create the source locale file, or fix `files.pattern` and `sourceLocale` in the config so they point at it. - **Nächster Schritt bei `import`**: Pass the path of the filled handoff file, or of the directory it was exported into, relative to the working directory or `--cwd`. - **Nächster Schritt bei `tmx import`**: Pass the path of an existing TMX file, relative to the working directory or `--cwd`. ### SOURCE_INVALID [#source_invalid] Die Quell-Locale-Datei konnte nicht gelesen oder geparst werden; umhüllt den Lesefehler des Adapters. Bei `import` und `tmx import` ist die zu importierende Datei zu groß oder kein lesbares Übergabe- bzw. TMX-Dokument. - **Ausgelöst von**: jeder Befehl, der Locale-Dateien liest; Studio und der MCP-Server - **Nächster Schritt**: Fix the file the message names so it parses under the configured format. - **Nächster Schritt bei `import`**: Fix the handoff file the message names, or pass its format with `--format` when its extension names none. - **Nächster Schritt bei `tmx import`**: Fix the TMX file the message names, or export it again from the tool that wrote it. ### LOCK_FILE_INVALID [#lock_file_invalid] Die Lock-Datei ist vorhanden, aber korrupt, übergroß oder in einer nicht unterstützten Version. - **Ausgelöst von**: `translate`, `import`, `check`, `diff`, `export`, `report`; Studio und der MCP-Server - **Nächster Schritt**: Restore verbatra.lock.json from version control, then try again. ### PROVENANCE_FILE_INVALID [#provenance_file_invalid] Die Herkunftsdatei ist vorhanden, aber korrupt, übergroß oder falsch aufgebaut; geworfen von einem Schreibvorgang (`translate`, `watch`, `importWorkbook`, `editEntry`, `retranslateEntry`, `approveEntry`, `rejectEntry`), bevor er etwas ändert, und von `loadProvenance`, nie von einem Bericht; eine von einem neueren verbatra bleibt stattdessen unangetastet, und `translate`, `watch` und `importWorkbook` melden die Notice `PROVENANCE_VERSION_UNRECOGNIZED`. - **Ausgelöst von**: `translate`, `watch`, `import`; Studio und der MCP-Server - **Nächster Schritt**: Restore verbatra.provenance.json from version control, then try again. ### PROVENANCE_FILE_UNWRITABLE [#provenance_file_unwritable] Eine Review-Entscheidung ließ sich nicht speichern, weil die Herkunftsdatei von einem neueren verbatra stammt oder über die Größe wachsen würde, die verbatra wieder einliest (`approveEntry`, `rejectEntry`, `approveLocale`); nichts wird geschrieben. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Upgrade verbatra if a newer version wrote verbatra.provenance.json, then record the decision again. ### REVIEW_VALUE_CHANGED [#review_value_changed] Der Key hat keinen Wert, oder sein Wert ist nicht der `expectedValue`, den die prüfende Person gesehen hat, oder `expectedValue` ist kein String (`approveEntry`, `rejectEntry`). - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Reload the current value, review it again, and resend the decision. ### REVIEW_SOURCE_CHANGED [#review_source_changed] Die Quelle hat sich geändert, seit der Wert geschrieben wurde, also lässt er sich so nicht freigeben (`approveEntry`). - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Edit or retranslate the key first, then review its new value. ### REVIEW_REJECT_UNSUPPORTED [#review_reject_unsupported] Das Format behält den Wert eines Keys, wenn die Datei ohne ihn geschrieben wird, wie XLIFF, oder die Locale-Datei ist zu groß, um eine Kopie zum Wiederherstellen aufzuheben, also hat `rejectEntry` die Datei gelassen, wie sie war. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Edit the value instead of rejecting it. ### REVIEW_RESTORE_FAILED [#review_restore_failed] `rejectEntry` ist nach dem Umschreiben der Locale-Datei gescheitert, und auch das Wiederherstellen der Locale-Datei oder der Herkunftsdatei schlug fehl; die Message nennt den ursprünglichen Fehler (auch die `cause`) und die Dateien, die du aus der Versionskontrolle wiederherstellst. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Restore the files the message names from version control. ### REVIEWER_INVALID [#reviewer_invalid] `reviewer` ist leer, länger als 64 Zeichen oder enthält ein Steuerzeichen (`approveEntry`, `rejectEntry`, `approveLocale`, `importWorkbook`). - **Ausgelöst von**: `import --reviewer`; Studio und der MCP-Server - **Nächster Schritt**: Pass a reviewer name of 1 to 64 characters with no control characters. ### LOCK_CONTENDED [#lock_contended] Die Schreibsperre einer Locale oder die Glossarsperre, die `updateGlossaryTerm` nimmt, konnte nicht vor ihrem Timeout erworben werden, oder ein anderer Prozess hat sie vor einem Schreibvorgang übernommen, den sie schützt, und es wurde nichts geschrieben; die Message nennt den Pfad der Lock-Datei. - **Ausgelöst von**: `translate`, `watch`, `import`; Studio und der MCP-Server - **Nächster Schritt**: Wait for the other verbatra process to finish and try again, or remove the lock file the message names if no process holds it. ### GLOSSARY_NOT_FILE_BACKED [#glossary_not_file_backed] Das Glossar der Konfiguration ist inline oder fehlt, es gibt also keine Glossardatei zum Lesen oder Neuschreiben (`readGlossaryFile`, `updateGlossaryTerm`). Ist gar kein Glossar konfiguriert, lautet der Hinweis stattdessen: Create a glossary file, such as glossary.json holding `{}`, and set the config's `glossary` to its path, such as `"glossary.json"`. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Move the glossary into its own file and set the config's `glossary` to that file's path. ### GLOSSARY_UNWRITABLE [#glossary_unwritable] Die Glossardatei konnte nicht geschrieben oder die Glossar-Schreibsperre nicht angelegt werden, etwa in einem schreibgeschützten Projekt, oder nach einer gespeicherten Änderung nicht freigegeben werden (`updateGlossaryTerm`); der Dateisystem-Fehler ist die `cause`. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Make the glossary file and its directory writable, then try again. ### LOCALE_LAYOUT_INVALID [#locale_layout_invalid] `files.pattern` und `files.localeStyle` lassen sich nicht kombinieren, oder der Style hat keine gültige Pfadschreibweise für eine konfigurierte Locale. - **Ausgelöst von**: jeder Befehl, der Locale-Dateien liest; Studio und der MCP-Server - **Nächster Schritt**: Fix `files.pattern` and `files.localeStyle` in the config so every locale maps to a valid path. ### LOCALE_PATH_COLLISION [#locale_path_collision] Zwei konfigurierte Locales lösen auf denselben absoluten Dateipfad auf. - **Ausgelöst von**: jeder Befehl, der Locale-Dateien liest; Studio und der MCP-Server - **Nächster Schritt**: Change `files.pattern` or `files.localeStyle` in the config so each locale resolves to its own file. ### CONCURRENCY_INVALID [#concurrency_invalid] `concurrency` wurde gesetzt, ist aber keine Ganzzahl von mindestens 1; wird geworfen, bevor eine Locale läuft. - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Pass a concurrency that is a whole number of at least 1. ### CONCURRENCY_BUDGET_CONFLICT [#concurrency_budget_conflict] Ein Live-Lauf setzte `concurrency` über 1, während ein Token-Budget gilt, konfiguriert oder für den Lauf; wird geworfen, bevor irgendein Provider-Aufruf stattfindet (ein Dry-Run ist ausgenommen). - **Ausgelöst von**: `translate`, `watch` - **Nächster Schritt**: Run with a concurrency of 1 while a token budget applies, or remove the budget. ### MAX_TOKENS_INVALID [#max_tokens_invalid] Das `maxTokens` pro Lauf von `translate` wurde gesetzt, ist aber keine ganze Zahl von mindestens 1; wird geworfen, bevor irgendetwas gelesen oder ausgegeben wird. - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Pass a token budget that is a whole number of at least 1. ### LOCK_TIMEOUT_INVALID [#lock_timeout_invalid] `lockAcquireTimeoutMs` wurde gesetzt, ist aber keine ganze Zahl von mindestens 0 Millisekunden (`translate`, `watch` beim Start, `importWorkbook`, `retranslateEntry`, `retranslateEntries`, `approveEntry`, `rejectEntry`, `approveEntries`, `rejectEntries`); wird geworfen, bevor irgendetwas gelesen oder gesperrt wird. - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Pass a lock timeout that is a whole number of at least 0. ### PAGE_CURSOR_INVALID [#page_cursor_invalid] Der an `localeValuesPage` oder `provenanceReportPage` übergebene `cursor` ist fehlerhaft, länger als `PAGE_CURSOR_MAX_LENGTH` (512), stammt aus anderen Filtern oder zeigt auf einen Key, der verschoben wurde oder fehlt, weil sich die Dateien zwischen zwei Seiten geändert haben. - **Ausgelöst von**: das SDK; das Agent-Tool `verbatra_locale_values` in Studio (der MCP-Server meldet ihn als ungültige Eingabe für `cursor`) - **Nächster Schritt**: Call again without a cursor to start from the first page. ### PAGE_LIMIT_INVALID [#page_limit_invalid] Das an `localeValuesPage` oder `provenanceReportPage` übergebene `limit` ist keine ganze Zahl von 1 bis `PAGE_LIMIT_CAP` (1000). - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Pass a page limit that is a whole number from 1 to 1000. ### TARGET_UNWRITABLE [#target_unwritable] Eine Ziel-Locale-Datei konnte nicht geschrieben werden (ihr Verzeichnis ist nicht schreibbar, existiert nicht, ist schreibgeschützt oder hat keinen Platz mehr); die Message nennt die Zieldatei und den Dateisystem-Code, nie die interne temporäre Datei, die der atomare Schreibvorgang nutzt. - **Ausgelöst von**: `translate`, `import`, `pseudo`; Studio und der MCP-Server - **Nächster Schritt**: Make the target locale file and its directory writable, then try again. ### PSEUDO_OUTPUT_CONFLICT [#pseudo_output_conflict] `pseudolocalize` wurde nach einer Pseudo-Locale gefragt, die eine konfigurierte Locale benennt, oder nach einem Ausgabepfad, der auf eine konfigurierte Locale-Datei oder außerhalb von `cwd` schreiben würde, auch nach dem Auflösen symbolischer Links; wird abgelehnt, bevor irgendetwas gelesen oder geschrieben wird. - **Ausgelöst von**: `pseudo` - **Nächster Schritt**: Choose a pseudolocale and an output path inside the project that name no configured locale. ### SOURCE_UNWRITABLE [#source_unwritable] Die Quell-Locale-Datei konnte nicht geschrieben werden (nur `extract`); `xliff` und `apple-xcstrings` erreichen ihn, wenn noch kein Katalog existiert, denn keines von beiden wird aus dem Nichts erzeugt. - **Ausgelöst von**: `extract` - **Nächster Schritt**: Make the source locale file writable; for xliff and apple-xcstrings, create the catalog first. ### EXTRACT_NOT_CONFIGURED [#extract_not_configured] `extract` wurde mit einer Konfiguration aufgerufen, die keinen `extract`-Block trägt. - **Ausgelöst von**: `extract` - **Nächster Schritt**: Add an `extract` block to the config naming the framework and source roots. ### EXTRACT_FS_UNSUPPORTED [#extract_fs_unsupported] `extract` bekam ein `deps.fs`, das kein `readDirectory` implementiert, es kann also keine Quelldatei gefunden werden. - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Pass a file system that implements `readDirectory`, or use the default one. ### TYPES_OUTPUT_CONFLICT [#types_output_conflict] `generateTypes` hat seinen Ausgabepfad abgelehnt: einen, der keine Datei benennt (oder auf ein Pfadtrennzeichen endet), absolut ist, mit `..` aus `cwd` herausklettert oder `cwd` selbst benennt oder nicht auf `.ts`, `.mts` oder `.cts` endet, und einen, der eine konfigurierte Locale-Datei, die Lock-Datei, die Herkunftsdatei, den Übersetzungsspeicher-Cache, eine Datei, nach der verbatra seine Konfiguration sucht, die geladene Konfigurationsdatei oder die Glossardatei der Konfiguration benennt, auch nach dem Auflösen symbolischer Links; ein schreibender Lauf weigert sich zusätzlich, eine vorhandene Datei zu ersetzen, die nicht mit verbatras Kopfzeile beginnt. - **Ausgelöst von**: `types` - **Nächster Schritt**: Choose a relative `.ts`, `.mts` or `.cts` output path inside the project that names no file verbatra manages. ### TYPES_UNWRITABLE [#types_unwritable] Die von `generateTypes` erzeugte Deklarationsdatei konnte nicht geschrieben werden (ihr Verzeichnis ist nicht schreibbar, existiert nicht, oder die Platte ist voll); die Message nennt die Datei und den Dateisystem-Code. - **Ausgelöst von**: `types` - **Nächster Schritt**: Make the output file and its directory writable, then try again. ### TMX_OUTPUT_CONFLICT [#tmx_output_conflict] `exportTmx` hat seinen Ausgabepfad abgelehnt: einen, der keine Datei benennt (oder auf ein Pfadtrennzeichen endet) oder außerhalb von `cwd` oder auf `cwd` selbst landet, und einen, der eine von verbatra verwaltete Datei benennt, wie unter [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict) aufgeführt, auch nach dem Auflösen symbolischer Links; wird abgelehnt, bevor der Übersetzungsspeicher gelesen wird. - **Ausgelöst von**: `tmx export` - **Nächster Schritt**: Choose an output path inside the project that names no locale file or other file verbatra manages. ### TMX_UNWRITABLE [#tmx_unwritable] Die von `exportTmx` erzeugte TMX-Datei konnte nicht geschrieben werden (ihr Verzeichnis ist nicht schreibbar, an dem Pfad liegt schon ein Verzeichnis, oder die Platte ist voll); die Message nennt die Datei und den Dateisystem-Code. - **Ausgelöst von**: `tmx export` - **Nächster Schritt**: Make the output file and its directory writable, then try again. ### MEMORY_UNWRITABLE [#memory_unwritable] Die Translation-Memory-Cache-Datei `verbatra.cache.json` konnte von `importTmx` nicht geschrieben werden (ihr Verzeichnis ist nicht beschreibbar, an ihrem Pfad liegt bereits ein Verzeichnis, oder der Speicherplatz ist erschöpft); die Meldung nennt die Datei und den Dateisystem-Code. - **Ausgelöst von**: `tmx import` - **Nächster Schritt**: Make verbatra.cache.json and its directory writable, then try again. ### EXPORT_OUTPUT_CONFLICT [#export_output_conflict] `exportWorkbook` hat seinen Ausgabepfad abgelehnt: einen, der außerhalb von `cwd` landet, und einen, der selbst oder über eine Datei, die der Export hineinschreiben würde, eine von verbatra verwaltete Datei benennt, wie unter [`TYPES_OUTPUT_CONFLICT`](#types_output_conflict) aufgeführt, auch nach dem Auflösen symbolischer Links; ein `xlsx`-Pfad, der keine Datei oder `cwd` selbst benennt, wird ebenfalls abgelehnt; wird abgelehnt, bevor irgendetwas gelesen wird. - **Ausgelöst von**: `export` - **Nächster Schritt**: Choose an output path inside the project that names no locale file or other file verbatra manages. ### EXPORT_UNWRITABLE [#export_unwritable] Die von `exportWorkbook` erzeugte Übergabe konnte nicht geschrieben werden (ihr Verzeichnis ist nicht schreibbar, ein Verzeichnis oder eine Datei liegt im Weg, oder die Platte ist voll); die Message nennt die Datei und den Dateisystem-Code, und der Dateisystem-Fehler ist die `cause`. - **Ausgelöst von**: `export` - **Nächster Schritt**: Make the output file and its directory writable, then try again. ### LOCALE_STATE_NOT_CARRIED_OVER [#locale_state_not_carried_over] Geworfen von `editEntry`, `retranslateEntry`, `approveEntry` und `rejectEntry`, die dann nichts schreiben, sonst steht er auf dem `error` einer Locale, die `translate`, `watch` oder `importWorkbook` nicht ausgeführt hat, weil ihr Zustand unter einem umgeschriebenen Code wie `pt_BR` in der Lock-Datei oder der Provenance-Datei nicht zu ihr verschoben werden konnte; der nächste Lauf versucht es erneut ([Ein umgeschriebener Locale-Code](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md#ein-umgeschriebener-locale-code)). - **Ausgelöst von**: `translate`, `watch`, `import`; Studio und der MCP-Server - **Nächster Schritt**: Wait for other verbatra processes to finish, make verbatra.lock.json and verbatra.provenance.json writable, then try again. ### LOCALE_UNSUPPORTED_BY_PROVIDER [#locale_unsupported_by_provider] Der konfigurierte Provider DeepL oder Google Cloud Translation führt die Quell-Locale oder eine ausgewählte Ziel-Locale nicht in der Sprachtabelle, die verbatra mitliefert; geworfen von `translate` (auch bei einem Dry-Run und einer Schätzung), `watch` beim Start und `retranslateEntry`, bevor ein Provider gebaut, ein Key gelesen oder eine Locale gestartet wird; einer Locale, die explizit in `localeMap` abgebildet ist, wird stattdessen vertraut ([Sprachunterstützung](https://verbatra.kreitz-webdev.de/de/docs/language-support.md#unterstützung-vor-einem-lauf-prüfen)). - **Ausgelöst von**: `translate`, `watch`; Studio und der MCP-Server - **Nächster Schritt**: Remove the unsupported locale from `targetLocales`, map it to a supported code in `provider.options.localeMap`, or choose a provider that supports it. ### NOT_A_LOCALE_FILE [#not_a_locale_file] `checkFile` hat einen Pfad bekommen, der zu keinem konfigurierten Locale gehört, oder dort gibt es keine Datei. - **Ausgelöst von**: `check --file` - **Nächster Schritt**: Pass the path of an existing locale file that `files.pattern` maps to a configured locale. ### SENSITIVE_CONTENT_WITHHELD [#sensitive_content_withheld] `retranslateEntry` hat den Key nicht gesendet oder seine Antwort verworfen, weil `sensitiveData.mode` auf `block` oder `redact` steht und der Key Inhalt enthält, den ein Detektor oder Muster getroffen hat und der nicht gesendet werden konnte oder nicht unverändert zurückkam ([Schutz für sensible Inhalte](https://verbatra.kreitz-webdev.de/de/docs/data-handling.md#schutz-für-sensible-inhalte)). `translate` und `watch` listen solche Keys stattdessen in `sensitiveWithheld`. - **Ausgelöst von**: Studio und der MCP-Server - **Nächster Schritt**: Remove the content from the key, list it in `sensitiveData.allow`, or turn the detector off in `sensitiveData.detectors`. ### RUN_CANCELLED [#run_cancelled] Das an `translate` oder `retranslateEntry` übergebene `signal` wurde abgebrochen. `retranslateEntry` wirft ihn, wenn der Abbruch kommt, bevor der Provider antwortet, und hat dann nichts geschrieben. `translate` vermerkt ihn auf jeder Locale, die durch den Abbruch nicht mehr startete, und markiert die Zusammenfassung als [`cancelled`](https://verbatra.kreitz-webdev.de/de/docs/sdk/run-summary.md). Ein Einstiegspunkt, der eine Schreibsperre nimmt, etwa `editEntry`, `approveEntry` oder `updateGlossaryTerm`, wirft ihn auch, wenn `releaseHeldLocks` gerade läuft, während er die Sperre nehmen will. - **Ausgelöst von**: nur das SDK - **Nächster Schritt**: Run the operation again to finish the work the cancellation left pending. ### LOCALE_FAILED [#locale_failed] Wird nie geworfen: der Rückfall-`code` auf dem `error` einer fehlgeschlagenen Locale. - **Ausgelöst von**: `translate`, `watch`, `import` - **Nächster Schritt**: Fix the cause the locale's message names, then try again. ## Provider-Fehlercodes [#provider-error-codes] Ein Provider-Fehler wirft einen `ProviderError` mit einem dieser Codes ([Strukturierte Fehler](https://verbatra.kreitz-webdev.de/de/docs/providers.md#strukturierte-fehler)). Innerhalb von `translate` und `watch` scheitert nur seine eigene Anfrage: deren Keys werden zurückgehalten, die Locale bekommt einen Hinweis `SUB_BATCH_FAILED` mit dem Code, und die Keys werden beim nächsten Lauf wieder aufgegriffen. Eine Neuübersetzung eines einzelnen Keys aus Studio oder dem MCP-Server wirft den `ProviderError` weiter. Eine gescheiterte Anfrage endet mit `1`, und ihre Locale endet `partial` oder `failed`. ### MISSING_API_KEY [#missing_api_key] Die erforderliche Umgebungsvariable ist ungesetzt oder leer. Die Meldung nennt die Variable, nie einen Wert, und in der CLI kommt er als `causeCode` von `PROVIDER_CONSTRUCTION_FAILED` mit Exit-Code `2` an. Bei LibreTranslate, dessen Key optional ist, heißt es, dass der Server einen Key verlangt hat und `LIBRETRANSLATE_API_KEY` nicht gesetzt ist. - **Nächster Schritt**: Set the API key environment variable your provider reads, then run `verbatra doctor`. ### INVALID_REQUEST [#invalid_request] Die Anfrage ist vor jedem Netzwerkaufruf an der Validierung gescheitert: ein fehlerhaftes Feld, ein Code, den DeepL nicht akzeptiert (ein `localeMap`-Eintrag mit einem regionalen Quell-Code oder ein Ziel, das auf ein bloßes `en` oder `pt` hinausläuft), oder ein Code, der bei Google Cloud Translation kein wohlgeformtes BCP-47 ist. Bei LibreTranslate deckt es auch eine Sprache ab, für die dein Server kein Modell hat, und eine Anfrage über seinem `--char-limit` oder `--batch-limit`. Wiederholen hilft nicht. - **Nächster Schritt**: Check the provider options in the config, such as the model name. ### INVALID_RESPONSE [#invalid_response] Die Ausgabe war fehlerhaft, unvollständig oder scheiterte am Abgleich mit der Anfrage. - **Nächster Schritt**: Try again; if it keeps failing, configure a different model. ### OUTPUT_TRUNCATED [#output_truncated] Das Modell hat sein Ausgabe-Token-Limit erreicht; siehe [Ausgabe-Token-Limits](https://verbatra.kreitz-webdev.de/de/docs/providers.md#ausgabe-token-limits). - **Nächster Schritt**: Translate fewer keys at a time, or configure a model with a larger output limit. ### PROVIDER_REFUSED [#provider_refused] Das Modell hat die Antwort verweigert. - **Nächster Schritt**: Review the source text the provider refused, or translate it by hand. ### PROVIDER_BLOCKED [#provider_blocked] Anfrage oder Antwort wurde aus Sicherheitsgründen blockiert oder gefiltert. - **Nächster Schritt**: Review the source text the provider blocked, or translate it by hand. ### RATE_LIMITED [#rate_limited] HTTP 429 oder ein SDK-Rate-Limit-Fehler. Bei Google Cloud Translation gehört hierzu auch ein HTTP 403, dessen Rumpf einen Kontingentgrund nennt (ein Tages- oder Minutenlimit). Google nutzt 403 sowohl für Kontingent- als auch für Zugangsdaten-Fehler, erhöhe also das Cloud-Translation-Kontingent deines Projekts. LibreTranslate meldet ein HTTP 403, dessen Fehlertext "too many" enthält, ebenfalls mit diesem Code, weil sein Server einen gesperrten Client mit 403 beantwortet. - **Nächster Schritt**: Wait a moment and try again, or lower the concurrency. ### TIMEOUT [#timeout] Ein Netzwerk- oder Anfrage-Timeout; [`requestTimeoutMs`](https://verbatra.kreitz-webdev.de/de/docs/providers.md#anfrage-timeout) hebt die Grenze an. - **Nächster Schritt**: Try again, or raise the provider's `requestTimeoutMs` in the config. ### AUTH_FAILED [#auth_failed] HTTP 401 oder 403: Der Key ist ungültig, widerrufen oder ohne Berechtigung. Bei den Providern Anthropic, OpenAI, Gemini, OpenCode und `openai-compatible` nennt die Meldung den Status und ergänzt bei 403, dass der Server die Anfrage wegen seiner Richtlinie oder der Rechte des Keys abgelehnt hat. Prüfe bei Google Cloud Translation, dass `GOOGLE_TRANSLATE_API_KEY` ein gültiger, uneingeschränkter Key für ein Projekt mit aktivierter Cloud Translation API ist. LibreTranslate meldet außerdem ein HTTP 400, dessen Fehlertext einen API-Key erwähnt, mit diesem Code, wenn ein Key konfiguriert ist. Wiederholen hilft nicht. - **Nächster Schritt**: Check that the provider's API key is valid and allowed to use the configured model. ### PROVIDER_UNAVAILABLE [#provider_unavailable] HTTP 5xx: Der Provider ist auf seiner eigenen Seite gescheitert, die Anfrage selbst war nie schuld. Wo ein Provider [wiederholt](https://verbatra.kreitz-webdev.de/de/docs/providers.md#wiederholungen), wird ein vorübergehendes 5xx abgefangen; ein 5xx, das diesen Code erreicht, ist dann eine anhaltende Störung. Google Cloud Translation und LibreTranslate wiederholen nicht, ein einzelnes 5xx landet hier also sofort. - **Nächster Schritt**: Try again later, or check the configured endpoint. ### NETWORK_POLICY_VIOLATION [#provider-network_policy_violation] Die [Netzwerkrichtlinie](https://verbatra.kreitz-webdev.de/de/docs/network-policy.md) hat die Anfrage direkt vor dem Senden abgelehnt: Der Hostname löste zu einer Adresse auf, die die Richtlinie nicht erlaubt, oder eine Antwort leitete zu einem abgelehnten Host weiter. Die Meldung nennt nur den Host. Wiederholen hilft nicht. - **Nächster Schritt**: Point the provider at a host the network policy permits, or add its host to `network.allowedHosts` or VERBATRA_NETWORK_ALLOWED_HOSTS. ### PROVIDER_ERROR [#provider_error] Alles Unklassifizierbare. Bei den Providern Anthropic, OpenAI, Gemini, OpenCode und `openai-compatible` nennt ein HTTP-Fehlschlag seinen Status, etwa `HTTP 404`, und den Fehlertyp des Servers, wenn er ein kurzes Token aus Buchstaben, Ziffern und Unterstrichen ist, etwa `MissingSessionID`; die eigene Meldung des Servers, der Antworttext und der URL-Pfad erscheinen nie. Bei einer `openai-compatible`-`baseUrl` ergänzt ein 404 oder 405 die Prüfung, ob `baseUrl` die API-Wurzel ist, und ein 400 oder 422 die Prüfung des Modellnamens und der Unterstützung für Chat Completions mit striktem JSON-Schema-Output; bei einem 4xx-Status hilft Wiederholen nicht. Ist der Fehlschlag ein erkennbares Transportproblem, benennt die Meldung es (Verbindung abgelehnt, Hostname nicht aufgelöst, Verbindung geschlossen, Host nicht erreichbar, TLS-Zertifikat nicht verifiziert) und sagt, was zu prüfen ist; sonst fällt sie auf eine statische, geheimnisfreie Meldung zurück. Konnte ein Provider-Paket nicht geladen werden, nennt die Meldung das Paket und rät, `@verbatra/sdk` neu zu installieren. - **Nächster Schritt**: Act on the cause or HTTP status the message names, then check the provider's `baseUrl` (if it takes one), `model` and the rest of the `provider` block in the config. ## Fehlercodes der Format-Adapter [#adapter-error-codes] Ein Format-Adapter, der eine Datei nicht verarbeiten kann, wirft einen `AdapterError` mit einem dieser Codes. Bei der Quell-Locale-Datei kommt er eingepackt in `SOURCE_INVALID` an, mit dem Code des Adapters als `causeCode`; bei einer Zieldatei wird er zum `error.code` dieser Locale. Jeder Befehl, der Locale-Dateien liest, Studio und der MCP-Server können ihn auslösen; die CLI endet mit `2`, wenn die Quelldatei schuld ist, und mit `1`, wenn eine Zieldatei ihre Locale in `translate` oder `import` scheitern lässt. `check --file` meldet eine Datei, die sich nicht parsen lässt, stattdessen als `syntax`-Befund. Die Menge ist geschlossen: Ein [eigener Adapter](https://verbatra.kreitz-webdev.de/de/docs/custom-format-adapters.md) wirft einen dieser Codes statt eines eigenen. ### INVALID_JSON [#invalid_json] Eine JSON-basierte Locale-Datei ist kein gültiges JSON. Die Meldung endet mit Zeile und Spalte, wenn der Parser sie meldet. - **Nächster Schritt**: Fix the syntax error the message names in that file. ### INVALID_YAML [#invalid_yaml] Eine YAML-Locale-Datei ist kein gültiges YAML. Die Meldung endet mit Zeile und Spalte, wenn der Parser sie meldet. - **Nächster Schritt**: Fix the syntax error the message names in that file. ### INVALID_XML [#invalid_xml] Eine XML-basierte Locale-Datei, etwa XLIFF oder Android-`strings.xml`, ist kein wohlgeformtes XML. - **Nächster Schritt**: Fix the syntax error the message names in that file. ### INVALID_STRUCTURE [#invalid_structure] Die Datei lässt sich parsen, hat aber nicht die Form, die das konfigurierte Format erwartet, zum Beispiel ein Key mit Punkten und ein verschachtelter Key-Pfad, die auf denselben Key hinauslaufen, oder ein YAML-Mapping-Key, der eine Map oder eine Sequenz ist. - **Nächster Schritt**: Reshape the file the message names to match the configured format. ### MAX_DEPTH_EXCEEDED [#max_depth_exceeded] Die Datei ist tiefer verschachtelt, als verbatra liest. - **Nächster Schritt**: Reduce the nesting depth of the file the message names. ### INPUT_TOO_LARGE [#input_too_large] Die Datei ist größer, als verbatra liest. - **Nächster Schritt**: Split the file the message names into smaller files. ### MIXED_STRUCTURE [#mixed_structure] Die Datei mischt flache und verschachtelte Keys, wo das Format das verbietet. - **Nächster Schritt**: Use either flat or nested keys throughout the file the message names. ### ADAPTER_FAILED [#adapter_failed] Ein `custom:`-Adapter hat einen unerwarteten Fehler geworfen. Der Fehler nennt das Format des Adapters, und der ursprüngliche Fehler des Adapters ist sein `cause`. - **Ausgelöst von**: das SDK, mit einem `custom:`-Adapter (die CLI lädt kein Plugin) - **Nächster Schritt**: Report the failure to the maintainer of the custom adapter the message names. ### DUPLICATE_FORMAT [#duplicate_format] Ein zweiter Adapter wurde für eine Formatkennung registriert, die die Registry schon hält. - **Ausgelöst von**: `AdapterRegistry.register` im SDK - **Nächster Schritt**: Register only one adapter for each format identifier. ### INVALID_FORMAT_ID [#invalid_format_id] Ein Adapter wurde unter einer fehlerhaften `custom:`-Kennung registriert. - **Ausgelöst von**: `AdapterRegistry.register` im SDK - **Nächster Schritt**: Name the custom adapter `custom:` followed by a valid name. ## Codes des Review-Gates [#check-result-codes] `check --require-reviewed` meldet, warum es scheitert, als `result.review.code` ([`verbatra check`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md)). ### REVIEW_REQUIRED [#review_required] Mindestens eine maschinell geschriebene Übersetzung (Herkunft `machine`, `memory`, `fuzzy` oder `agent`) ist in der committeten `verbatra.provenance.json` nicht freigegeben. Der Envelope bleibt `ok: true`, und `result.locales[].review.unreviewed` nennt die Keys. - **Ausgelöst von**: `check --require-reviewed` - **Exit-Code**: `1` - **Nächster Schritt**: Gib die genannten Keys in der [Review-Warteschlange von Studio](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md) oder mit den MCP-Tools `review.approve` und `review.reject` frei oder korrigiere sie, und committe dann `verbatra.provenance.json`. ### REVIEW_STATE_UNREADABLE [#review_state_unreadable] `verbatra.provenance.json` ist beschädigt oder stammt von einem neueren verbatra, also lässt sich kein Review-Stand lesen, und das Gate schlägt sicherheitshalber fehl. - **Ausgelöst von**: `check --require-reviewed` - **Exit-Code**: `1` - **Nächster Schritt**: Stelle `verbatra.provenance.json` aus der Versionskontrolle wieder her, oder aktualisiere verbatra, wenn eine neuere Version die Datei geschrieben hat. ## Gründe für Integritätsablehnungen [#integrity-refusal-reasons] Das [Integritäts-Gate](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#das-integritäts-gate) lehnt einen Kandidatenwert mit genau einem dieser Gründe ab, dem ersten, der in der dort genannten Reihenfolge zutrifft. Der Grund steht nach `translate`, `watch` und `import` in den `integrityRefusals` einer Locale (`integrity-withheld` in der Ausgabe für Menschen), im Ergebnis von `editEntry` und von `retranslateEntry` (`accepted: false` mit dem `reason`) und als Fehler von `check --qa`, oft mit `details`, die nennen, was abweicht. Eine Ablehnung endet mit `1` bei `check --qa` und bei `translate` und `import`, wenn die Locale partial oder failed endet. Die Menge wird als Tupel `INTEGRITY_GATE_REASONS` ausgeliefert. ### placeholder [#placeholder] Die Platzhalter des Kandidaten weichen von denen seiner Quelle ab, verglichen als Multimenge: Die Anzahl zählt, die Reihenfolge nicht. Was als Platzhalter gilt, legt jedes [Format](https://verbatra.kreitz-webdev.de/de/docs/formats.md) fest. Bei i18next, ngx-translate und YAML wird auch ein Token der Form `{name}` abgelehnt, das der Kandidat hinzufügt und die Quelle nie hatte, obwohl einfache geschweifte Klammern dort wörtlicher Text sind. Die Details nennen jeden weggelassenen Platzhalter mit `-` und jeden hinzugefügten mit `+`, etwa `-{{name}}` oder `+{{nom}}`. - **Nächster Schritt**: Setze die Platzhalter der Quelle wieder in die Übersetzung ein oder lass den nächsten Lauf sie neu übersetzen. ### markup [#markup] Das Inline-HTML- oder -XML-Markup des Kandidaten weicht von dem seiner Quelle ab oder ist nicht wohlgeformt. Die Details nennen jedes Tag hinter der Ablehnung, mit `-` für eines, das die Quelle hatte und der Kandidat weggelassen hat, oder mit `+` für eines, das der Kandidat erfunden hat. - **Nächster Schritt**: Behalte die Tags, Attributnamen und geschützten Attributwerte der Quelle in der Übersetzung bei. #### Wie Markup verglichen wird [#wie-markup-verglichen-wird] Tags werden als Multimenge aus Tag-Namen plus Attributnamen verglichen: - Abgelehnt: ein weggelassenes Tag, ein erfundenes Tag, ein umbenanntes Tag, ein geänderter Satz von Attributnamen (auch ein ergänztes `dir`-Attribut für ein Ziel mit Schreibrichtung von rechts nach links), Markup, das unausgeglichen oder falsch verschachtelt zurückkommt, etwa `ab`, sowie ein Tag, das in einem anderen gleichen Namens verschachtelt zurückkommt, obwohl die Quelle sie nebeneinander hatte, denn so werden aus zwei Links still und leise einer. - Akzeptiert: dieselben Tags in anderer Reihenfolge, ein geänderter Attributwert wie ein übersetztes `title` oder ein lokalisiertes `href` (innerhalb der weiter unten beschriebenen Grenzen für Attributwerte), und beide Schreibweisen eines leeren Elements, `
` und `
` sind dasselbe Tag. - Gezählt, nicht nur bemerkt: zwei benachbarte Paare, die zu einem verschmolzen werden (`a b` wird `a b`), werden abgelehnt. - Exakt verglichen: Eine Änderung der Groß- und Kleinschreibung ist ein Befund. Die leeren HTML-Elemente (`
`, ``, `
` und die übrigen) brauchen in jeder Schreibweise kein schließendes Tag, `
` wird also genauso als leeres Element erkannt wie `
`. Auch eine Quelle ganz ohne Markup ist gegen hineinerfundenes Markup geschützt. Der Kandidat wird abgelehnt für jedes Tag-Paar, jedes leere Element und jedes selbstschließende Tag, das er ergänzt, für ein schließendes Tag ohne öffnendes (`Hallo`) und für ein nie geschlossenes öffnendes Tag, das mehr als seinen Namen trägt, etwa `` oder ``. Ein nie geschlossenes ``, das nur aus seinem Namen besteht und dessen Name nur Buchstaben, Ziffern, Bindestriche und Unterstriche enthält, ist ein Wort in spitzen Klammern, etwa `` in `Druecke `. Solche Wörter werden auf beiden Seiten beiseitegelegt, bevor die Quelle beurteilt wird, eine Quelle mit einem solchen Wort wird also trotzdem verglichen: Ein Kandidat, der neben `` ein ``-Paar weglässt oder ein `` wird für das `` abgelehnt. Wo ein Parser diesen Inhalt auf zwei Arten lesen kann, wird der Kandidat abgelehnt, es sei denn, er ist die unveränderte Quelle, mit einem Detail wie `+`: ein `script`, dessen Inhalt `