Troubleshooting

Each entry starts from what you see and links the code behind it to Error codes, which lists every code with its meaning, exit code and next step. Search by the code in verbatra: error [CODE], never by the message text.

Run verbatra doctor before you go entry by entry: it checks the config, the format, the provider, the API key variable and the source file in one pass, spends nothing, and works before the source locale file exists.

pnpm blocks a dependency's install scripts (ERR_PNPM_IGNORED_BUILDS)Copy Anchor Link

Symptom: pnpm add -D @verbatra/cli prints its install summary and then exits 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 also writes a pnpm-workspace.yaml into your project holding an unanswered choice:

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

Until you answer it, every later pnpm command in that project fails the same way, including pnpm exec verbatra init.

Cause: pnpm does not run a third-party dependency's install scripts unless you allow them. @google/genai and its transitive protobufjs declare such scripts, and the Gemini SDK is installed whichever provider you configure, so every pnpm install path hits this. Nothing in verbatra declares an install script of its own, and npm and yarn install the same package without a prompt. The install itself did complete: node_modules/.bin/verbatra already works.

Fix: answer the choice once. Interactively, run pnpm approve-builds and approve neither entry. Non-interactively, which is what you want in CI, write the answer before you install by putting this in pnpm-workspace.yaml at the project root:

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

verbatra does not need those scripts, and this repository declines both. With the answer in place pnpm add -D @verbatra/cli exits 0 and later pnpm commands run normally. The package versions in the message track the release; the fix does not change.

The configuration is invalid (CONFIG_INVALID)Copy Anchor Link

Symptom: The verbatra configuration is invalid: ..., with one issue per field.

Cause: the config was found but fails validation, for example a files.pattern without {locale}, a locale code that is not BCP 47 (such as en_US), or an unknown key. An unknown key gets the note API keys are read from the environment, not the config: the schema is strict so a secret cannot hide in a committed file.

Fix: correct the field the message names; see The config file. For No verbatra configuration found..., see CONFIG_NOT_FOUND. Code: CONFIG_INVALID.

No adapter for the format (UNKNOWN_FORMAT)Copy Anchor Link

Symptom: No adapter is registered for format "...", followed by the supported list.

Cause: the config's format is not a registered id. A custom: format cannot run from the command line, which loads no plugin.

Fix: use an id from Formats. For a custom: format, run through the SDK with a registry that holds its adapter: see Write a custom format adapter. Code: UNKNOWN_FORMAT.

Requested locale is not configured (UNKNOWN_LOCALE)Copy Anchor Link

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

Cause: --locales (or an SDK locales input) names a locale that is not in targetLocales. A filter selects from the configured list; it never adds to it.

Fix: add the locale to targetLocales, or fix the typo. Code: UNKNOWN_LOCALE.

The source file is missing or unparseable (SOURCE_UNREADABLE, SOURCE_INVALID)Copy Anchor Link

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

Cause: files.pattern with the source locale filled in points at no file, or the file does not parse. The path is resolved against the project root, the directory of the config the search found (or the working directory with --config), so a wrong --cwd or --config is a common cause, and so is a wildcard: files.pattern is a literal path, not a glob (see Namespace layouts).

Fix: check the printed path. For a parse failure, the causeCode names the format adapter code. Codes: SOURCE_UNREADABLE, SOURCE_INVALID.

Missing API key (PROVIDER_CONSTRUCTION_FAILED)Copy Anchor Link

Symptom: Failed to construct provider "anthropic": The ANTHROPIC_API_KEY environment variable is not set. (or your provider's variable).

Cause: the variable the message names is unset or empty. Keys come only from the environment, never from the config or a flag.

Fix: set the variable and confirm it with verbatra doctor. The CLI also reads it from .env.local and .env; the SDK does not, so use node --env-file=.env in your own script. Codes: PROVIDER_CONSTRUCTION_FAILED, MISSING_API_KEY.

Rate limits, timeouts, and auth failures mid-run (RATE_LIMITED, TIMEOUT, AUTH_FAILED)Copy Anchor Link

Symptom: the run completes, but some keys are listed under providerFailures with a SUB_BATCH_FAILED notice naming the provider code, and the command exits 1.

Cause: a provider request failed after the provider was built: HTTP 429, a timeout, or HTTP 401/403.

Fix: nothing is lost; the keys are picked up again on the next run. Re-run later for RATE_LIMITED, after the wait its message names if it names one (an exhausted daily quota), and one locale at a time with --locales against a strict quota. For a slow model, raise requestTimeoutMs against TIMEOUT. AUTH_FAILED does not resolve by retrying: replace the key.

The lock file is corrupt (LOCK_FILE_INVALID)Copy Anchor Link

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

Cause: verbatra.lock.json was hand-edited, truncated, damaged in a merge, or written by an incompatible version. translate and import stop the whole run on it, and locales committed before the stop keep what they wrote.

Fix: restore the file from version control. Deleting it also clears the error, but loses the baselines, so earlier source edits are no longer seen as stale. See The lock file. Code: LOCK_FILE_INVALID.

A locale file could not be written (TARGET_UNWRITABLE)Copy Anchor Link

Symptom: a locale fails with Could not write the locale file locales/de.json (EACCES). ...

Cause: the file or its directory is not writable: permissions, a missing directory, a read-only mount, or a full disk. The write goes through a temporary file in the same directory, so the directory must be writable too.

Fix: fix what the file-system code names and re-run. Only that locale fails, and it keeps its previous file and baseline. Code: TARGET_UNWRITABLE.

Another process holds the write lock (LOCK_CONTENDED)Copy Anchor Link

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

Cause: another translate, watch, import or Studio write holds the locale's lock. A lock left by a dead process on this machine is reclaimed automatically, so a lingering one comes from another machine or a verbatra older than 0.12.0.

Fix: wait for the other run, or delete the printed lock file if no verbatra process runs anywhere. --lock-timeout <seconds> on translate, watch and import changes how long a run waits. Code: LOCK_CONTENDED.

Dotted keys or YAML keys collide (INVALID_STRUCTURE)Copy Anchor Link

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

Cause: two entries in one file resolve to the same key, such as "a.b" next to a: { b: ... }, or a YAML key has no string form. verbatra refuses rather than dropping one.

Fix: rename one of the keys, or use a scalar YAML key. In the source file this arrives inside SOURCE_INVALID. Code: INVALID_STRUCTURE.

The run stopped short of some keys (token budget)Copy Anchor Link

Symptom: a BUDGET_TOKENS_EXCEEDED notice; under budgetBehavior: "stop" keys are also listed under budgetWithheld.

Cause: the run reached maxTokens in the config or --max-tokens for the run. "warn" only reports a budget set in the config; "stop", and --max-tokens whatever the config says, withhold every key not yet attempted, and the locale ends partial or failed.

Fix: this is the guardrail working: what landed is written, and withheld keys are translated on the next run. Raise the budget or switch to "warn" for one-run completion. How the budget is counted is in Translation safety. Code: BUDGET_TOKENS_EXCEEDED.

A translation is withheld for inline markup (integrity mismatch)Copy Anchor Link

Symptom: a key is listed under integrityMismatches and keeps its previous value, or Studio shows Rejected: inline markup mismatch with the tags at fault: -<a href> for a tag the candidate dropped, +<i> for one it invented. verbatra check --qa reports the same for values already on disk.

Cause: the candidate does not carry the source's inline tags, or carries them unbalanced or mis-nested, so the integrity gate refuses it like a dropped placeholder.

Fix: run the key again, or fix the value by hand in Studio or a workbook; the same gate judges both. What is compared, and the refusals that are by design, are in Inline markup parity.

Studio: the port is already in useCopy Anchor Link

Symptom: port 5849 is already in use (or your --port value).

Cause: another process, often an earlier Studio, is bound to the port.

Fix: stop it, or start Studio on another port: verbatra studio --port 6000.

Studio: @verbatra/studio is not installedCopy Anchor Link

Symptom: Verbatra Studio requires @verbatra/studio., followed by the install commands.

Cause: Studio is a separate package the studio command loads on demand.

Fix: npm install --save-dev @verbatra/studio, or for a one-off run npx -y -p @verbatra/cli -p @verbatra/studio verbatra studio. With pnpm, see pnpm blocks a dependency's install scripts first.

npx @verbatra/cli runs the CLI installed in the package of the current folder, so run it from the project root (or use pnpm exec verbatra in a workspace subpackage); anywhere else npx fetches the latest CLI, which may not match your local @verbatra/studio or @verbatra/mcp.

Studio: retranslate and translate actions are missingCopy Anchor Link

Symptom: editing works, but the retranslate and translate-pending actions do not appear.

Cause: provider spend is granted at startup, under the rules in Spend and agent tools, and without it the spend actions are not registered.

Fix: restart with verbatra studio --allow-spend, unless the project is human-only. See Review in Studio.

MCP: @verbatra/mcp is not installedCopy Anchor Link

Symptom: Verbatra's MCP server requires @verbatra/mcp., followed by the install commands.

Cause: the MCP server is a separate package the mcp command loads on demand, so npx -y @verbatra/cli mcp alone never works.

Fix: run npx -y @verbatra/mcp, or install @verbatra/mcp next to the CLI and re-run verbatra mcp. With pnpm, see pnpm blocks a dependency's install scripts first.

MCP: an agent's tools/list never shows translation.retranslateEntry or translation.translatePendingCopy Anchor Link

Symptom: the local tools work, but the two spend tools are absent, and calling one fails as an unknown tool.

Cause: spend is granted at startup, under the rules in Spend tools, and the tool list must not change per connection, so the spend tools are left out entirely.

Fix: restart with verbatra mcp --allow-spend, unless the project is human-only.

Undoing a run (no error code)Copy Anchor Link

verbatra has no undo command; version control is the recovery path. Revert the locale files, verbatra.lock.json and verbatra.provenance.json together, never the locale files alone. See Recovery and rollback.