UltraGXTroubleshooting and FAQ
Installation and start-up
Windows shows "Windows protected your PC". It is SmartScreen with an installer that still has little reputation. Click More info → Run anyway. If your organisation blocks that option, ask your IT support to allow the installer.
The UltraGX window opens blank or does not open (Windows). The Microsoft Edge WebView2 runtime is missing or damaged. Install it from the Microsoft page ("WebView2 Runtime", Evergreen installer) and open UltraGX again. The UltraGX installer adds it automatically.
The application does not open on Linux. Run it from a terminal (ultragx or the AppImage) to see the error. If it mentions libwebkit2gtk, install libwebkit2gtk-4.1-0 (Debian/Ubuntu) or webkit2gtk4.1 (Fedora).
macOS says UltraGX "cannot be opened". The macOS build is not signed with an Apple Developer ID. Double-click Allow UltraGX.command in the disk image after dragging UltraGX to Applications (or run xattr -cr /Applications/UltraGX.app in Terminal), or allow it in System Settings → Privacy & Security → Open Anyway.
Licence
"The licence service could not be reached" appears. The computer cannot reach https://licenses.ultra-gx.com. Check the internet connection; on corporate networks, ask for HTTPS to that domain to be allowed (also through the proxy). The other registration messages are explained in First start and licence.
The run ends with "A valid license file (ultragx.lic) is required…" or code 3. The licence is missing, has expired or has been revoked. Check Settings → License. If the demo has ended, write to us to move to the full edition.
In the demo, no object came out detailed. The run could not check with the licence service and continued without a sample. The reason is in the notice in the README.md and in the viewer. Fix the connection and run the pipeline again.
I changed computers. The licence is bound to the machine where it was activated. Write to us with the new This machine id to move it.
Documenting a KB
The "live" source appears disabled. Settings → Environment shows why: GeneXus connector: not found (Linux, macOS or a copy without the connector) or GeneXus installed: none detected. In those cases export the KB to XPZ on the machine where GeneXus is.
The live export does not progress or fails when opening the KB. The KB is open in the GeneXus IDE or in another tool: close it and run again. If the log repeats the same object for several minutes, the connector is still extracting a large object; on KBs with thousands of objects the export can take more than an hour.
I chose the wrong GeneXus version. Leave auto (from the KB). Force an installation only if the KB opens with a different version from the one detected.
Some SDTs or transactions appear without structure. If the KB was documented with a version earlier than 0.2.5, run it again with the current version (with the live source, the export too).
Acceptance ended in warning. The documentation was generated in full; the quality check found something to review. The detail is under Acceptance in the viewer. failed indicates a problem worth reporting.
The summary warns library_flag_suspect. Almost all objects were flagged as library, which indicates an export that did not separate own objects from referenced ones properly. Export the KB again (with the current connector, if it is live).
Paths or folder names are too long (Windows). The output mirrors the modules and folders of the KB. Use a short output folder, such as D:\ultragx.
The output folder is in OneDrive / Dropbox and everything is slow. Synchronisation processes thousands of files at once. Use a folder outside synchronised folders.
Narrative
| Message in the log | Cause | Solution |
|---|---|---|
401, 403, invalid API key | the connection key is not valid or has no permission for that model | check the connection's API key |
404, model not found | the model name does not exist at that provider | correct Model with a name from the provider's catalogue |
429, quota, rate limit | provider usage limit | the engine retries on its own; if it persists, lower Concurrency or check your account quota |
| connection refused with a local model | the local server is not running or the URL is wrong | start Ollama / LM Studio and check the Base URL |
many degraded | the model cites names that do not exist | try a more capable model; with local models, increase the context size |
The prose does not appear in the viewer. Click Reload. Only objects in ok are published.
Where to look
| What | Where |
|---|---|
| Log of a run | Jobs → Log while the application is open |
| Result of the run | run_summary.json and acceptance_report.md in the project folder |
| Narrative status | narrative/checkpoint.json and one JSON per object in narrative/ |
| Settings and licence | %APPDATA%\UltraGX (Windows) or ~/.config/UltraGX (Linux and macOS) |
Support
Write to us at contact@ultra-gx.com with:
- the UltraGX version (Settings → Environment → App) and the operating system;
- the error message or the end of the job log;
- the project's
run_summary.jsonandacceptance_report.md, if the problem is with a run.
Do not send the XPZ, the KB code or the complete output folder unless we ask for it and your organisation authorises it.
Frequently asked questions
Does UltraGX modify my KB? No. It only reads: the connector has no write path at all and with an XPZ it does not even touch the KB.
Do I need GeneXus installed? Only for the live source. With an XPZ or a text export, no.
Which GeneXus versions does it support? From 7.5 to 18 via XPZ/XML; from X Evolution 1 to 18 live.
Can I document the same KB many times? Yes. With the same project name it is regenerated in the same folder and notes and narrative are kept. In the demo, the 25-object sample is always the same.
Can I share the documentation? Yes: the project folder is self-contained and the viewer works offline. Bear in mind that it contains the KB code.
Is the source code sent anywhere? Only if you use the narrative with a cloud provider, and only to that provider. See AI narrative.