UltraGXSolución de problemas y preguntas frecuentes
Instalación y arranque
Windows muestra "Windows protegió su PC". Es SmartScreen con un instalador que todavía tiene poca reputación. Hacé clic en Más información → Ejecutar de todas formas. Si tu organización bloquea esa opción, pedile a soporte técnico que habilite el instalador.
La ventana de UltraGX se abre en blanco o no se abre (Windows). Falta el runtime Microsoft Edge WebView2 o está dañado. Instalalo desde la página de Microsoft ("WebView2 Runtime", instalador Evergreen) y volvé a abrir UltraGX. El instalador de UltraGX lo agrega solo.
La aplicación no abre en Linux. Ejecutala desde una terminal (ultragx o la AppImage) para ver el error. Si menciona libwebkit2gtk, instalá libwebkit2gtk-4.1-0 (Debian/Ubuntu) o webkit2gtk4.1 (Fedora).
macOS dice que UltraGX "no se puede abrir". La versión de macOS no está firmada con un Developer ID de Apple. Hacé doble clic en Allow UltraGX.command de la imagen de disco después de arrastrar UltraGX a Aplicaciones (o ejecutá xattr -cr /Applications/UltraGX.app en Terminal), o autorizala en Configuración del Sistema → Privacidad y seguridad → Abrir igualmente.
Licencia
Aparece "No se pudo contactar al servicio de licencias". El equipo no llega a https://licenses.ultra-gx.com. Verificá la conexión a internet; en redes corporativas, pedí que permitan HTTPS a ese dominio (también a través del proxy). Los demás mensajes del registro están explicados en Primer inicio y licencia.
La ejecución termina con "A valid license file (ultragx.lic) is required…" o código 3. La licencia falta, venció o fue revocada. Revisá Configuración → Licencia. Si la demo terminó, escribinos para pasar a la edición completa.
En la demo, ningún objeto salió detallado. La ejecución no pudo consultar el servicio de licencias y siguió sin muestra. El motivo está en el aviso del README.md y del visor. Resolvé la conexión y volvé a ejecutar el pipeline.
Cambié de computadora. La licencia queda atada a la máquina donde se activó. Escribinos con el nuevo Id de esta máquina para moverla.
Documentar una KB
La fuente "live" aparece deshabilitada. Configuración → Entorno muestra por qué: Conector GeneXus: no encontrado (Linux, macOS o una copia sin conector) o GeneXus instalado: ninguno detectado. En esos casos exportá la KB a XPZ en la máquina donde está GeneXus.
La exportación en vivo no avanza o falla al abrir la KB. La KB está abierta en el IDE de GeneXus o en otra herramienta: cerrala y volvé a ejecutar. Si el log repite el mismo objeto durante varios minutos, el conector sigue extrayendo un objeto grande; en KB de miles de objetos la exportación puede llevar más de una hora.
Elegí la versión de GeneXus equivocada. Dejá auto (desde la KB). Forzá una instalación solo si la KB se abre con una versión distinta de la que se detecta.
Algunos SDTs o transacciones aparecen sin estructura. Si la KB se documentó con una versión anterior a la 0.2.5, volvé a ejecutarla con la versión actual (con la fuente live, también la exportación).
La aceptación terminó en warning. La documentación se generó completa; el control de calidad encontró algo a revisar. El detalle está en Aceptación, en el visor. failed indica un problema que conviene reportar.
El resumen avisa library_flag_suspect. Casi todos los objetos quedaron marcados como librería, lo que indica un export que no separó bien los objetos propios de los referenciados. Volvé a exportar la KB (con el conector actual, si es en vivo).
Las rutas o los nombres de carpeta son muy largos (Windows). La salida replica los módulos y carpetas de la KB. Usá una carpeta de salida corta, como D:\ultragx.
La carpeta de salida está en OneDrive / Dropbox y todo va lento. La sincronización procesa miles de archivos a la vez. Usá una carpeta fuera de las carpetas sincronizadas.
Narrativa
| Mensaje en el log | Causa | Solución |
|---|---|---|
401, 403, invalid API key | la clave de la conexión no es válida o no tiene permisos para ese modelo | revisá la API key de la conexión |
404, model not found | el nombre del modelo no existe en ese proveedor | corregí Modelo con un nombre del catálogo del proveedor |
429, quota, rate limit | límite de uso del proveedor | el motor reintenta solo; si persiste, bajá Concurrencia o revisá la cuota de tu cuenta |
| connection refused con un modelo local | el servidor local no está corriendo o la URL no es la correcta | iniciá Ollama / LM Studio y verificá la URL base |
muchos degraded | el modelo cita nombres que no existen | probá un modelo más capaz; con modelos locales, subí el tamaño de contexto |
La prosa no aparece en el visor. Hacé clic en Recargar. Solo se publican los objetos en ok.
Dónde mirar
| Qué | Dónde |
|---|---|
| Log de una ejecución | Tareas → Log mientras la aplicación está abierta |
| Resultado de la ejecución | run_summary.json y acceptance_report.md en la carpeta del proyecto |
| Estado de la narrativa | narrative/checkpoint.json y un JSON por objeto en narrative/ |
| Configuración y licencia | %APPDATA%\UltraGX (Windows) o ~/.config/UltraGX (Linux y macOS) |
Soporte
Escribinos a contact@ultra-gx.com con:
- la versión de UltraGX (Configuración → Entorno → Aplicación) y el sistema operativo;
- el mensaje de error o el final del log de la tarea;
run_summary.jsonyacceptance_report.mddel proyecto, si el problema es de una ejecución.
No mandes el XPZ, el código de la KB ni la carpeta de salida completa salvo que te lo pidamos y tu organización lo autorice.
Preguntas frecuentes
¿UltraGX modifica mi KB? No. Solo lee: el conector no tiene ningún camino de escritura y con un XPZ ni siquiera toca la KB.
¿Necesito GeneXus instalado? Solo para la fuente live. Con un XPZ o un export de texto, no.
¿Qué versiones de GeneXus soporta? De la 7.5 a la 18 por XPZ/XML; de X Evolution 1 a 18 en vivo.
¿Puedo documentar la misma KB muchas veces? Sí. Con el mismo nombre de proyecto se regenera en la misma carpeta y se conservan notas y narrativa. En la demo, la muestra de 25 objetos es siempre la misma.
¿Puedo compartir la documentación? Sí: la carpeta del proyecto es autocontenida y el visor funciona sin conexión. Tené en cuenta que contiene el código de la KB.
¿El código fuente se envía a algún lado? Solo si usás la narrativa con un proveedor en la nube, y a ese proveedor. Ver Narrativa con IA.