Solución de problemas

Clave API requerida

API key required for gemini backend.

  Option 1: Set via config:
    yaku config set api-key your-api-key

  Option 2: Set environment variable:
    export YAKU_API_KEY=your-api-key

  Option 3: Use hosted service (no key needed):
    yaku config set backend hosted

Este error aparece cuando usa un backend local (Gemini, OpenAI, Anthropic) sin una clave API.

Solución: Siga una de las tres opciones mostradas en el mensaje de error. La vía más simple es usar el backend alojado, que no necesita clave API:

yaku config set backend hosted

O configure una clave API para su backend preferido. Consulte Backends para instrucciones completas de configuración.

No se especificó idioma destino

Error: target language required. Use --to <lang> or set default:

  yaku config set default-target ja

Solución: Pase --to o configure un predeterminado:

# Por comando
yaku --to es "Hello"

# Configurar un predeterminado
yaku config set default-target es

Código de idioma inválido

Error: unknown language "japanese". Did you mean "ja"?

Solución: Use un código BCP 47, no el nombre del idioma:

# Incorrecto
yaku --to japanese "Hello"

# Correcto
yaku --to ja "Hello"

Consulte Idiomas para códigos comunes.

Modo inválido

Error: invalid mode "xxx". Use "translate" or "polish"

Solución: La opción --mode solo acepta translate (predeterminado) o polish:

yaku --mode translate --to es "Hello"
yaku --mode polish --to es "corregir la gramatica"

Error de red / API inaccesible

Error: failed to reach Gemini API. Check your network connection

Solución:

1. Verifique su conexión a internet.
2. Si está detrás de un proxy, configure las variables de entorno HTTP_PROXY/HTTPS_PROXY.
3. Si usa un proveedor compatible con OpenAI, verifique que --api-base sea correcto.

Entrada demasiado larga

Error: input too long (8000 chars). Hosted service limit: 5000 chars per request

Este error aparece cuando su texto excede el límite de caracteres por solicitud para su plan. El límite depende de su nivel de plan — consulte Servicio alojado y planes para detalles.

Solución:

• Inicie sesión — yaku login eleva el límite de 5,000 (anónimo) a 10,000 (gratuito) caracteres.
• Divida el texto en partes más pequeñas.
• Use un backend local (Gemini, OpenAI, Anthropic) con su propia clave API — los backends locales no tienen límite de caracteres.
• Verifique sus límites actuales con yaku quota.

Cuota excedida

Error: Daily limit reached (50/50). Run "yaku login" for higher limits, or use your own API key: yaku config set api-key
More info: https://docs.yakulang.com/guides/hosted-service/

Ha usado todas sus solicitudes diarias o mensuales en el servicio alojado.

Solución:

• Inicie sesión — yaku login eleva su límite mensual de 100 (anónimo) a 300 (gratuito).
• Use su propia clave API — yaku config set api-key <clave> con un backend local no tiene límites de cuota.
• Espere — los límites diarios se reinician a medianoche UTC.
• Verifique su uso actual con yaku quota.

Consulte Servicio alojado y planes para detalles completos de planes.

Modelo no encontrado

Error: model not found or no longer available. Omit --model to use the default

Este error aparece cuando el valor de --model no coincide con ningún modelo disponible en su backend.

Solución:

• Omita --model para usar el modelo predeterminado.
• Verifique el nombre del modelo contra la documentación de su proveedor.

Límite de tasa excedido

Error: API rate limit exceeded.

Solución: Espere y reintente. Si esto ocurre frecuentemente:

• Cambie a un backend diferente (--backend openai)
• Use el backend alojado con yaku login para cuotas más altas
• Consulte la documentación de límites de tasa de su proveedor de API

Clave API inválida o no autorizada

Error: invalid or unauthorized API key. Check your key:

  yaku config get api-key
  yaku config set api-key <new-key>

Solución:

1. Verifique su clave: yaku config get api-key
2. Compruebe que la clave coincida con el backend que está usando (ej., una clave de Gemini con --backend gemini, no --backend openai).
3. Regenere la clave desde el panel de su proveedor.

Tiempo de solicitud agotado

Error: request timed out. The API did not respond in time. Try again later

Solución: yaku tiene un timeout de 30 segundos por solicitud. Para archivos grandes:

• Divida el archivo en partes más pequeñas
• Verifique la velocidad de su conexión a internet
• Pruebe un backend diferente

Salida vacía

Si yaku no produce salida:

1. ¿La entrada está vacía? (echo "" | yaku no devuelve nada)
2. Use --verbose para verificar que la llamada a la API fue exitosa:

   echo "test" | yaku --to es --verbose

3. Verifique si la salida está siendo redirigida: yaku --to es "test" 2>/dev/null

Error de sintaxis en archivo de configuración

Warning: config file ~/.config/yaku/config.yaml has invalid YAML syntax: ...
  Open the file and fix the syntax, or delete it and reconfigure:
    ~/.config/yaku/config.yaml
  Using default config until fixed.

Solución: yaku registra una advertencia pero continúa con los predeterminados. Para corregir:

# Encontrar el archivo de configuración
yaku config path

# Editarlo manualmente o reiniciar eliminándolo
rm ~/.config/yaku/config.yaml
yaku config set default-target es

Valor de configuración inválido

Error: invalid value "abcdefg" for backend. Valid values: hosted, gemini, openai, anthropic

Este error aparece al ejecutar yaku config set con un valor no reconocido.

Solución: Use uno de los valores válidos mostrados en el mensaje de error. Por ejemplo:

yaku config set backend gemini

Los campos validados incluyen backend (debe ser uno de hosted, gemini, openai, anthropic) y default-target (debe ser un código de idioma BCP 47 válido).

YAKU_API_KEY está establecida pero vacía

Error: YAKU_API_KEY is set but empty (check your key source).

  Example: YAKU_API_KEY=$(cat /path/to/key) yaku --backend gemini ...

Este error aparece cuando YAKU_API_KEY está establecida como cadena vacía — típicamente porque un comando de obtención de clave falló silenciosamente (ej., $(vault read ...) no devolvió nada).

Solución: Verifique el comando o archivo que proporciona su clave. Si no pretende establecer YAKU_API_KEY, elimínela:

unset YAKU_API_KEY

Sesión expirada o inválida

Session expired or invalid. Run yaku login to re-authenticate.

Este error aparece al ejecutar yaku whoami y la sesión almacenada ya no es válida. El CLI refresca sesiones automáticamente, pero si la sesión ha expirado completamente, necesita reautenticarse.

Solución: Reautentíquese:

yaku login

El glosario no se carga

Si los términos del glosario no se están aplicando:

1. Verifique que el archivo existe: ls .yaku-glossary.yaml
2. Verifique que la sección del idioma coincida con su destino --to (insensible a mayúsculas): es: para --to es
3. Use --glossary <ruta> para carga explícita
4. Asegúrese de que --no-glossary no esté configurado

¿Sigue atascado?

Abra un issue con:

• Su versión de yaku (yaku version)
• El comando que ejecutó
• El mensaje de error completo
• Su configuración de backend (yaku config get backend)