Solución de problemas

Cada entrada parte de lo que ves y enlaza el código que hay detrás con Códigos de error, donde cada código aparece con su significado, su código de salida y su siguiente paso. Busca por el código de verbatra: error [CODE], nunca por el texto del mensaje.

Ejecuta verbatra doctor antes de ir entrada por entrada: comprueba la config, el formato, el proveedor, la variable de la clave de API y el archivo fuente de una sola pasada, no gasta nada y funciona antes de que exista el archivo de locale fuente.

pnpm bloquea los scripts de instalación de una dependencia (ERR_PNPM_IGNORED_BUILDS)Copiar enlace a esta sección

Síntoma: pnpm add -D @verbatra/cli imprime su resumen de instalación y luego sale con 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 además escribe un pnpm-workspace.yaml en tu proyecto con una decisión sin responder:

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

Mientras no la respondas, cualquier comando pnpm posterior en ese proyecto falla igual, incluido pnpm exec verbatra init.

Causa: pnpm no ejecuta los scripts de instalación de una dependencia de terceros salvo que se lo permitas. @google/genai y su protobufjs transitivo declaran esos scripts, y el SDK de Gemini se instala sea cual sea el proveedor que configures, así que toda instalación con pnpm lo toca. verbatra no declara ningún script de instalación propio, y npm y yarn instalan el mismo paquete sin preguntar. La instalación sí se completó: node_modules/.bin/verbatra ya funciona.

Solución: responde la decisión una vez. De forma interactiva, ejecuta pnpm approve-builds y no apruebes ninguna de las dos entradas. De forma no interactiva, que es lo que quieres en CI, deja la respuesta escrita antes de instalar poniendo esto en el pnpm-workspace.yaml de la raíz del proyecto:

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

verbatra no necesita esos scripts, y este repositorio rechaza los dos. Con la respuesta puesta, pnpm add -D @verbatra/cli sale con 0 y los comandos pnpm posteriores funcionan con normalidad. Las versiones de los paquetes del mensaje siguen al lanzamiento; la solución no cambia.

La configuración es inválida (CONFIG_INVALID)Copiar enlace a esta sección

Síntoma: The verbatra configuration is invalid: ..., con un problema por campo.

Causa: la config se encontró, pero no pasa la validación, por ejemplo un files.pattern sin {locale}, un código de locale que no es BCP 47 (como en_US) o una clave desconocida. Una clave desconocida recibe la nota API keys are read from the environment, not the config: el esquema es estricto para que ningún secreto se esconda en un archivo confirmado.

Solución: corrige el campo que nombra el mensaje; consulta Archivo de configuración. Para No verbatra configuration found..., consulta CONFIG_NOT_FOUND. Código: CONFIG_INVALID.

No hay adaptador para el formato (UNKNOWN_FORMAT)Copiar enlace a esta sección

Síntoma: No adapter is registered for format "...", seguido de la lista de formatos admitidos.

Causa: el format de la config no es un id registrado. Un formato custom: no funciona desde la línea de comandos, que no carga ningún plugin.

Solución: usa un id de Formatos. Para un formato custom:, trabaja con el SDK y un registro que contenga su adaptador: consulta Escribe un adaptador de formato propio. Código: UNKNOWN_FORMAT.

El locale solicitado no está configurado (UNKNOWN_LOCALE)Copiar enlace a esta sección

Síntoma: Requested locale not in the configured target locales: ...

Causa: --locales (o una entrada locales del SDK) nombra un locale que no está en targetLocales. Un filtro elige de la lista configurada; nunca la amplía.

Solución: añade el locale a targetLocales, o corrige la errata. Código: UNKNOWN_LOCALE.

El archivo de origen falta o no se puede analizar (SOURCE_UNREADABLE, SOURCE_INVALID)Copiar enlace a esta sección

Síntoma: The source locale file was not found at <path>. o The source locale file at <path> could not be read: ...

Causa: files.pattern con el locale fuente sustituido no apunta a ningún archivo, o el archivo no se puede parsear. La ruta se resuelve contra la raíz del proyecto, el directorio de la configuración encontrada (o el directorio de trabajo con --config), así que un --cwd o un --config equivocado es una causa habitual, igual que un comodín: files.pattern es una ruta literal, no un glob (consulta Diseños con namespaces).

Solución: revisa la ruta impresa. Si falla el parseo, el causeCode nombra el código del adaptador de formato. Códigos: SOURCE_UNREADABLE, SOURCE_INVALID.

Falta la clave de API (PROVIDER_CONSTRUCTION_FAILED)Copiar enlace a esta sección

Síntoma: Failed to construct provider "anthropic": The ANTHROPIC_API_KEY environment variable is not set. (o la variable de tu proveedor).

Causa: la variable que nombra el mensaje no está definida o está vacía. Las claves solo vienen del entorno, nunca de la config ni de un flag.

Solución: define la variable y confírmala con verbatra doctor. La CLI también la lee de .env.local y .env; el SDK no, así que usa node --env-file=.env en tu propio script. Códigos: PROVIDER_CONSTRUCTION_FAILED, MISSING_API_KEY.

Límites de tasa, tiempos de espera y fallos de autenticación a mitad de ejecución (RATE_LIMITED, TIMEOUT, AUTH_FAILED)Copiar enlace a esta sección

Síntoma: la ejecución termina, pero algunas claves aparecen en providerFailures con un aviso SUB_BATCH_FAILED que nombra el código del proveedor, y el comando sale con 1.

Causa: una petición al proveedor falló después de construirlo: HTTP 429, un tiempo de espera agotado o HTTP 401/403.

Solución: no se pierde nada; las claves se retoman en la siguiente ejecución. Con RATE_LIMITED, vuelve a ejecutar más tarde, tras la espera que nombre el mensaje si nombra una (una cuota diaria agotada), y un locale cada vez con --locales si la cuota es estricta. Para un modelo lento, sube requestTimeoutMs frente a TIMEOUT. AUTH_FAILED no se resuelve reintentando: cambia la clave.

El archivo de bloqueo está corrupto (LOCK_FILE_INVALID)Copiar enlace a esta sección

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

Causa: verbatra.lock.json se editó a mano, se truncó, se dañó en un merge o lo escribió una versión incompatible. translate e import detienen toda la ejecución por ello, y los locales confirmados antes de la parada conservan lo que escribieron.

Solución: restaura el archivo desde el control de versiones. Borrarlo también quita el error, pero pierde las líneas base, así que los cambios anteriores en la fuente ya no se detectan como obsoletos. Consulta El archivo de bloqueo. Código: LOCK_FILE_INVALID.

No se pudo escribir un archivo de locale (TARGET_UNWRITABLE)Copiar enlace a esta sección

Síntoma: un locale falla con Could not write the locale file locales/de.json (EACCES). ...

Causa: el archivo o su directorio no se pueden escribir: permisos, un directorio que no existe, un montaje de solo lectura o un disco lleno. La escritura pasa por un archivo temporal en el mismo directorio, así que el directorio también debe poder escribirse.

Solución: arregla lo que nombra el código del sistema de archivos y vuelve a ejecutar. Solo falla ese locale, y conserva su archivo y su línea base anteriores. Código: TARGET_UNWRITABLE.

Otro proceso tiene el bloqueo de escritura (LOCK_CONTENDED)Copiar enlace a esta sección

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

Causa: otro translate, watch, import o una escritura de Studio tiene el bloqueo del locale. Un bloqueo que dejó un proceso muerto en esta máquina se recupera solo, así que uno que persiste viene de otra máquina o de un verbatra anterior a 0.12.0.

Solución: espera a la otra ejecución, o borra el archivo de bloqueo impreso si no hay ningún proceso de verbatra en marcha en ninguna parte. --lock-timeout <seconds> en translate, watch e import cambia cuánto espera una ejecución. Código: LOCK_CONTENDED.

Claves con puntos o claves YAML colisionan (INVALID_STRUCTURE)Copiar enlace a esta sección

Síntoma: A dotted key and a nested key path resolve to the same path. o, en YAML, A mapping key is a map or sequence (expected scalar keys).

Causa: dos entradas de un archivo llevan a la misma clave, como "a.b" junto a a: { b: ... }, o una clave YAML no tiene forma de cadena. verbatra lo rechaza en lugar de descartar una.

Solución: renombra una de las claves, o usa una clave YAML escalar. En el archivo fuente llega envuelto en SOURCE_INVALID. Código: INVALID_STRUCTURE.

La ejecución se quedó corta con algunas claves (presupuesto de tokens)Copiar enlace a esta sección

Síntoma: un aviso BUDGET_TOKENS_EXCEEDED; con budgetBehavior: "stop" además aparecen claves en budgetWithheld.

Causa: la ejecución alcanzó maxTokens de la config o --max-tokens de la ejecución. "warn" solo informa de un presupuesto de la config; "stop", y --max-tokens diga lo que diga la config, retienen cada clave aún no intentada, y el locale termina partial o failed.

Solución: es la barrera de seguridad funcionando: lo que llegó está escrito, y las claves retenidas se traducen en la siguiente ejecución. Sube el presupuesto o cambia a "warn" si quieres completarlo todo en una ejecución. Cómo se cuenta el presupuesto está en Seguridad de la traducción. Código: BUDGET_TOKENS_EXCEEDED.

Una traducción se retiene por el marcado en línea (discordancia de integridad)Copiar enlace a esta sección

Síntoma: una clave aparece en integrityMismatches y conserva su valor anterior, o Studio muestra Rejected: inline markup mismatch con las etiquetas culpables: -<a href> para una que el candidato perdió, +<i> para una que inventó. verbatra check --qa informa de lo mismo para valores que ya están en disco.

Causa: el candidato no lleva las etiquetas en línea de la fuente, o las lleva desequilibradas o mal anidadas, así que la puerta de integridad lo rechaza como a un marcador perdido.

Solución: vuelve a ejecutar la clave, o corrige el valor a mano en Studio o en un libro; la misma puerta juzga ambos. Qué se compara y qué rechazos son intencionados está en Paridad del marcado en línea.

Studio: el puerto ya está en usoCopiar enlace a esta sección

Síntoma: port 5849 is already in use (o tu valor de --port).

Causa: otro proceso, a menudo un Studio anterior, ocupa el puerto.

Solución: detenlo, o arranca Studio en otro puerto: verbatra studio --port 6000.

Studio: @verbatra/studio no está instaladoCopiar enlace a esta sección

Síntoma: Verbatra Studio requires @verbatra/studio., seguido de los comandos de instalación.

Causa: Studio es un paquete aparte que el comando studio carga cuando lo necesita.

Solución: npm install --save-dev @verbatra/studio, o para una ejecución puntual npx -y -p @verbatra/cli -p @verbatra/studio verbatra studio. Con pnpm, lee antes pnpm bloquea los scripts de instalación de una dependencia.

npx @verbatra/cli ejecuta la CLI instalada en el paquete de la carpeta actual, así que lánzalo desde la raíz del proyecto (o usa pnpm exec verbatra en un subpaquete del workspace); en otro lugar npx descarga la CLI más reciente, que puede no coincidir con tu @verbatra/studio o @verbatra/mcp local.

Studio: faltan las acciones de retraducir y traducirCopiar enlace a esta sección

Síntoma: editar funciona, pero las acciones de retraducir y de traducir claves pendientes no aparecen.

Causa: el gasto en el proveedor se concede al arrancar, según las reglas de Gasto y herramientas de agente, y sin ese permiso las acciones de gasto no se registran.

Solución: reinicia con verbatra studio --allow-spend, salvo que el proyecto sea solo humano. Consulta Revisar en Studio.

MCP: @verbatra/mcp no está instaladoCopiar enlace a esta sección

Síntoma: Verbatra's MCP server requires @verbatra/mcp., seguido de los comandos de instalación.

Causa: el servidor MCP es un paquete aparte que el comando mcp carga cuando lo necesita, así que npx -y @verbatra/cli mcp por sí solo nunca funciona.

Solución: ejecuta npx -y @verbatra/mcp, o instala @verbatra/mcp junto a la CLI y vuelve a ejecutar verbatra mcp. Con pnpm, lee antes pnpm bloquea los scripts de instalación de una dependencia.

MCP: el tools/list de un agente nunca muestra translation.retranslateEntry ni translation.translatePendingCopiar enlace a esta sección

Síntoma: las herramientas locales funcionan, pero faltan las dos herramientas de gasto, y llamar a una por su nombre falla como herramienta desconocida.

Causa: el gasto se concede al arrancar, según las reglas de Herramientas de gasto, y la lista de herramientas no puede cambiar según la conexión, así que las herramientas de gasto quedan fuera por completo.

Solución: reinicia con verbatra mcp --allow-spend, salvo que el proyecto sea solo humano.

Deshacer una ejecución (sin código de error)Copiar enlace a esta sección

verbatra no tiene un comando para deshacer; el control de versiones es el camino de vuelta. Revierte los archivos de locale, verbatra.lock.json y verbatra.provenance.json juntos, nunca solo los archivos de locale. Consulta Recuperación y reversión.