Troubleshooting

Entries are ordered by how often they occur. Log excerpts are the exact text written to C:\ProgramData\VRAI\HEATCapture\Logs\log.txt.

The application window is blank

Cause. The Microsoft Edge WebView2 Runtime is not installed. The interface is a web view; without the runtime there is nothing to render. The installer does not check for it.

Fix. Install the WebView2 Runtime from Microsoft and restart the application. The log records Not installed for WebView2 on startup when it is absent.

A session will not start and the interface reports insufficient storage

Cause. The drive holding the capture store has less free space than StorageSettings:MinimumFreeSpaceBytes, 5 GiB by default. The request is refused before anything is recorded.


Cannot start capture session: {StoragePath} has {AvailableBytes} bytes free, below the {MinimumBytes} byte minimum.

Fix. Free space on that drive, or move the store to a data drive with StorageSettings:BaseDirectory. Delivered session directories in the capture store are the usual culprit, since nothing removes them automatically. Confirm a session has no pending data before deleting it, using GET /api/storage/pending-sessions.

Cause. The signed-in account is missing fields the platform requires.


Cannot start capture session: logged-in user is missing or incomplete (UserId={UserId}, Username='{Username}', Email='{Email}'). Re-login required.

Fix. Sign out and sign in again. If it recurs, the account itself is incomplete on the platform; ask your HEAT administrator to check it.

Capture stopped by itself part-way through an exercise

Cause. One of the two data-safety stops fired. Either free space fell below the minimum:


Stopping capture because the HARDStore drive is below its minimum free-space threshold.

or the internal write queue filled, which means the disk could not keep up with the modules:


Storage append queue rejected a packet because it is full or stopping; stopping capture to prevent further data loss.

Fix. For the first, free space or move the store. For the second, record onto a faster local disk; a network share or a heavily contended drive will not sustain high packet rates. Data already recorded is intact in both cases.

Data is not arriving on the platform, but capture keeps running

Cause. Delivery is failing while recording continues, which is the intended behaviour. After MaxBundleRetries attempts the packets are parked for the next launch.


Parked {Count} packet(s) for node {NodeId} after {Retries} failed delivery attempts; will retry next launch.

Fix. Restore connectivity to the platform. Nothing is lost: the packets are on disk marked pending, and are replayed on a later launch once a user is signed in. Check the queue with GET /api/storage/pending-sessions.

Pending data is never replayed

Cause. Replay is gated twice. A user must be signed in with a valid token, and the platform URL recorded in the session must match the configured HEATSettings:HEAT_URL. Sessions recorded against a different URL are skipped on purpose.

Fix. Sign in, and confirm the configured URL matches the one used during recording. If the URL was changed deliberately, an administrator can force delivery with POST /api/storage/pending-sessions/{id}/retry.

A module refuses to load after being copied onto the machine

Cause. The package has no trusted VRAI signature, or its files were modified after signing. Signature verification runs again from disk every time a module starts.


Module '{name}' failed signature verification and will not be loaded: {reason}

Fix. Install the module through the application from a configured source rather than copying files in. Do not edit files inside an installed module directory. If a signed package genuinely fails, the download is corrupt; reinstall it.

A module disappeared mid-session and will not come back

Cause. It failed to stop when asked and was quarantined for the rest of the application run.


Module {ModuleName} didn't stop correctly and has been quarantined. It will not run again until the application is restarted. From here on there will be dragons.

Fix. Restart the application between exercises. Report a reproducible case to VRAI with the log attached, since a module that will not stop is a defect in that module.

A module keeps restarting

Cause. Its process is exiting and the watchdog is retrying it with a growing delay of 1, 5, 15 then 30 minutes.


Module {ModuleName} died unexpectedly (IsRunning = false). It will be eligible to retry after its cooldown.

Fix. Check the module’s own prerequisites: hardware attached, vendor runtime installed, source application running. The module page lists them. Ten minutes of healthy running clears the failure count.

Modules cannot be installed or changed

Cause. Either a session is active, or package changes are disabled for this workstation.


Blocking {Operation} for {Package}: package mutations are disabled

Fix. Stop the session. If the block persists, the workstation is locked down with Modules:AllowPackageMutations set to false, which is deliberate on accredited machines and needs a configuration change and a restart to undo.

The interface is unreachable from another machine

Cause. The server is bound to loopback, or a firewall is blocking the port. No firewall rule is created at install time.

Fix. Decide first whether remote access is warranted; most endpoints perform no authentication. If it is, set WebSettings:Host to the workstation’s address, add a firewall rule limited to the hosts that need it, and restart.

HTTPS was enabled but only HTTP answers

Cause. The resolved HTTPS port is invalid or clashes with the HTTP port, so the listener was skipped and HTTP was kept up. The log records the resolved values.

Fix. Set WebSettings:HttpsPort to a free port in 1 to 65535 that differs from WebSettings:Port, and restart. The HTTPS listener binds every network interface regardless of WebSettings:Host.

Collecting diagnostics for VRAI

Attach all of the following:

C:\ProgramData\VRAI\HEATCapture\Logs\log.txt and its rolled siblings
The output of GET /api/operations/summary
The output of GET /api/storage/capacity
The application version from GET /api/ui/version

Do not send heat.modules.json: it contains your Module Library token in clear text. If VRAI needs it, remove the token value first.

HEAT Capture team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.