15. Solución de problemas (Troubleshooting) y FAQ

Objetivo del tema

Reunir los incidentes más comunes que aparecen al trabajar con Gemini CLI, identificar cómo mitigarlos y ofrecer respuestas inmediatas a las dudas típicas de soporte.

La idea es que puedas diagnosticar rápido, escalar cuando haga falta y documentar qué pasos repetir antes de contactar al equipo.

15.1 Errores comunes y sus soluciones

La siguiente tabla recopila los síntomas reportados con mayor frecuencia, el origen probable y pasos concretos para resolverlos.

Síntoma Causa probable Acción sugerida
command not found o el binario no inicia. Instalación corrupta o ruta sin incluir node_modules/.bin.
  • Reinstala el paquete con npm: npm install -g @google/gemini-cli.
  • Verifica que el PATH incluya la carpeta global de npm.
  • En entornos empresariales, confirma permisos de ejecución.
Respuesta 401 Unauthorized. Clave de API inexistente, token vencido o escoplo incorrecto.
  • Ejecuta gemini auth login o actualiza el secreto en ~/.config/gemini/config.json.
  • Comprueba que la cuenta tenga acceso habilitado a Gemini API.
429 Too Many Requests o tiempo de espera agotado. Se alcanzó la cuota por minuto o hay latencia en la región.
  • Reduce el ritmo automático con --rate-limit o vuelve a intentar con retroceso exponencial.
  • Evalúa cambiar de región en el archivo de configuración.
Error invalid_request al enviar prompts. Formato JSON invalido o payload supera el límite permitido.
  • Valida el schema con gemini tools validate.
  • Segmenta la entrada en chunks y usa checkpointing para reanudar.
Logs indican tool not registered. Plugin sin registrar o extensión ubicada fuera de carpeta confiable.
  • Revisa la sección tools del archivo de configuración.
  • Agrega el directorio al listado de carpetas confiables y recarga el CLI.

Cuando un error no aparezca en la tabla, habilita gemini --debug para ver el stack trace, toma nota de la versión y comparte el log en el canal de soporte.

Consejo: mantén Node.js actualizado; la versión mínima recomendada aparece en la documentación oficial. Puedes comprobarla con node --version.

15.2 Límites, cuotas y pricing

Gemini CLI consume la API de Gemini administrada desde Google Cloud. Las cuotas y el costo dependen del modelo elegido y de la organización asociada a tu proyecto.

  • Cuotas por proyecto: cada clave tiene asignados límites por minuto, día y cuenta. Ajusta valores en la consola de Google Cloud o solicita un aumento con justificativo del caso de uso.
  • Modelos y precios: los modelos más potentes consumen más créditos por millón de tokens. Consulta el tarifario vigente en Google AI Studio para planificar presupuestos.
  • Límites de almacenamiento: el caché de memoria y artefactos temporales del CLI se rota automáticamente; si trabajas con grandes volúmenes, configura rutas externas y limpia con regularidad.
  • Monitor de consumo: ejecuta gemini usage report --period=7d para generar un resumen local que facilite detectar picos.

Si tu empresa gestiona la facturación centralizada, coordina con el administrador para obtener reportes agregados y definir alertas de gasto.

15.3 Preguntas frecuentes

¿Cómo limpio la configuración cuando el CLI se comporta de forma extraña?

Respaldá ~/.config/gemini/config.json y elimina la carpeta state/. Luego ejecuta gemini init para regenerar valores por defecto. Esta acción no borra tus extensiones.

¿Puedo usar el CLI sin conexión a Internet?

No. El CLI necesita comunicarse con la API para resolver prompts. Solo los comandos relacionados con archivos locales y scripts funcionan offline, pero la generación se suspende hasta recuperar conectividad.

¿Qué diferencia hay entre un error del CLI y uno de la API?

Errores del CLI suelen activarse antes de enviar la solicitud (por ejemplo, validaciones locales o extensiones). Los errores de la API regresan códigos HTTP y mensajes con prefijos como GeminiApiError. Revisa el campo requestId para escalarlo a soporte.

¿Dónde reporto bugs o solicito nuevas funciones?

Abre un issue en el repositorio oficial y adjunta la información de diagnóstico generada con gemini doctor --output=log.json. Incluye sistema operativo, versión del CLI y pasos para reproducir.

¿Es posible compartir cuotas entre equipos?

Sí, configura proyectos separados en Google Cloud pero bajo la misma cuenta de facturación. Luego crea claves por equipo y define reglas de IAM para limitar el uso según rol.

Conclusión: tener a mano estas guías te permite responder en minutos a incidentes recurrentes, anticipar sobrecostos y registrar aprendizajes en tu base interna de conocimiento.

Retornar