On this page

Troubleshooting

What an isolen app leaves behind when something goes wrong: the log, a crash line with the module and offset that faulted, a minidump on Windows, and the Vulkan validation layer on request.

The log

Every app under isolen_open or isolen_run writes the file named by isolen_app_desc::log, beside the executable. A backend switch logs each step, and so does a Vulkan teardown, so a hang or a crash shows the last step that finished. See switching live for the switch lines.

Vulkan teardown lineMeans
vulkan teardown waiting for the queuesThe teardown started and waits for submitted work.
vulkan teardown device idleThe GPU finished everything.
vulkan teardown retire ring drainedResources waiting to be freed are freed.
vulkan teardown assets passes and sync destroyedImages, passes, fences and semaphores are gone.
vulkan teardown swapchain destroyedThe swapchain is gone.
gpu surface destroyed, gpu device destroyedThe last native objects are gone.

The crash guard

The app shell turns on a crash guard right after the log opens, and logs crash guard on. A fault nobody catches then leaves a line in the log before the process dies. Code that runs without the shell can call log_crash_guard() from isolenui/core/log.h itself.

  • Windows. An unhandled exception logs its code, the module it hit and the offset into it, and the thread. For an access violation it also says whether it was a read, write or execute, and of which address. It also writes a minidump beside the executable, named EXE_crash_YYYYMMDD_HHMMSS.dmp, for example isolen_gallery_crash_20260924_101530.dmp. When that folder is read only the dump goes to the temp folder and the log line says where. The line reads [ crash ] fatal unhandled exception CODE in NAME at offset 0x... (MODULE), thread N, minidump written to PATH.
  • macOS. A signal handler for SIGSEGV, SIGBUS, SIGILL and SIGFPE logs the signal, the address it touched, and the module and offset of the faulting instruction, then lets the process die as it would have. The line reads [ crash ] fatal signal N touching ADDRESS, pc in MODULE offset 0x.... The system crash report is still written as usual.

The module and offset are usually enough on their own. A crash in nvoglv64.dll or another driver module points at a native GPU object used after its device was closed, which is what switch listeners prevent. Open a minidump in Visual Studio or WinDbg with the matching PDB for the full stack.

When you report a crash, send the log file and, on Windows, the .dmp beside the executable.

Vulkan validation

--vk-validate turns on the Khronos validation layer, VK_LAYER_KHRONOS_validation, for that run. Its warnings and errors go to the same log, which says vulkan validation layer on, its warnings and errors go to this log. When the layer is not installed the log says validation layer requested but not installed and the app runs without it. The layer ships with the Vulkan SDK.

  • In code it is gfx_desc::validate, for a device you open yourself.
  • A build configured with ISOLEN_VALIDATION on always asks for the layer, flag or not.
  • Validation slows every frame down. Use it to find a bug, not for the event.

Last updated 6 October 2026