Troubleshooting Spirit Vale Overlay on Windows

This guide covers the portable Windows x64 release of Spirit Vale Overlay. Work through the sections that match the symptom you see.

Quick recovery checklist

  1. Confirm that the computer is running 64-bit Windows 10 version 1809 or newer, or Windows 11.
  2. Install or repair the required components:
  3. Restart Windows after installing or repairing Npcap or the runtimes.
  4. Download the latest ZIP from GitHub Releases.
  5. If you are unable to extract the zip, right-click it, choose Properties, select Unblock if that option is present, and then extract it. You can scan the zip with antivirus/view as needed.
  6. Extract the entire ZIP to a normal writable local folder, such as C:\Users\<you>\Games\SpiritValeOverlay. Do not run the executable from inside the ZIP. Avoid protected folders such as C:\Program Files, network drives, and cloud-synced folders while troubleshooting.
  7. Run spirit-vale-overlay-win_x64.exe from the extracted folder.

The portable release already includes the Bun runtime it needs at extensions\bin\bun.exe. End users do not need to install Bun separately.

The app does not open or immediately closes

Re-extract a clean copy

An incomplete extraction or a security product removing one file can prevent startup.

  1. Close every Spirit Vale Overlay window.
  2. In Task Manager, end any remaining spirit-vale-overlay-win_x64.exe or bun.exe process that belongs to the extracted app folder.
  3. Keep the old folder temporarily if it contains settings you need.
  4. Download the release ZIP again and extract it to a new folder.
  5. Confirm that the new folder contains at least:
    • spirit-vale-overlay-win_x64.exe
    • resources.neu
    • extensions\backend\index.js
    • extensions\bin\bun.exe
  6. Start the executable from the new folder.

Do not copy only the main .exe; the app requires the other files in the release folder.

Check Windows Security

Open Windows Security > Virus & threat protection > Protection history and look for an action involving the Spirit Vale executable, extensions\bin\bun.exe, or another file in the extracted folder.

If Windows Security removed a file, first confirm that the ZIP came from the official GitHub Releases page. Restore or allow the file only if you trust that download, then extract a fresh copy. Prefer allowing the specific detected file or app over disabling antivirus protection or excluding a broad folder. If the warning remains, include its exact detection name and affected path in a bug report.

If Windows shows a SmartScreen prompt, use More info to inspect the publisher and file name before deciding whether to run it.

Test the bundled backend

From PowerShell in the extracted application folder, run:

& ".\extensions\bin\bun.exe" --version

It should print a version number and exit. If the file is missing, blocked, or will not start, re-extract the ZIP and check Windows Security. Installing a separate global copy of Bun does not replace the bundled runtime used by the app.

Try elevated permissions as a diagnostic

Right-click spirit-vale-overlay-win_x64.exe and choose Run as administrator once. Running the overlay as administrator is only required if Restrict Npcap driver’s access to Administrators only is unchecked during the main install.

The window is blank or never finishes loading

  1. Install or repair the WebView2 Runtime, then restart Windows.
  2. Close all leftover Spirit Vale Overlay and bundled bun.exe processes before trying again.
  3. Reset only the WebView/runtime state as described below.
  4. Make sure security software is not blocking local loopback traffic. Neutralino and the backend communicate on 127.0.0.1 using temporary local ports.
  5. If the window is still blank after all of the above, try the Electron build instead (see below).

Try the Electron build

Releases ship two ZIPs. The default spirit-vale-overlay-windows-x64-vX.Y.Z.zip uses Neutralino + WebView2. The larger spirit-vale-overlay-electron-windows-x64-vX.Y.Z.zip is a feature-equivalent fallback that bundles its own Chromium, so it does not depend on WebView2 at all. Reach for it when WebView2 will not install or repair, or when windows render with wrong borders/transparency. Run Spirit Vale Overlay.exe from the extracted folder; it is portable and stores data the same way (data\ beside the executable, with .spirit-vale-portable present). The two builds can be kept side by side.

Reset settings or cached runtime data

Close the app before changing its data. If possible, export settings first from Settings > Manage Settings.

The default portable release stores data beside the executable:

To test whether cached runtime state is corrupt, rename data\runtime to data\runtime.old and restart the app. If that does not help, restore the old folder or delete the newly created replacement.

To test with entirely fresh portable data, rename data to data.old and restart. This resets settings as well as cached state, but the renamed folder remains available for recovery.

If .spirit-vale-portable has been removed from the application folder, the app instead creates new data under:

%APPDATA%\Spirit Vale Overlay\data

Deleting .spirit-vale-portable changes the location used on the next start; it does not move existing data automatically.

The app opens but capture or DPS does not work

Verify Npcap

  1. Re-run the Npcap installer.
  2. Select Install Npcap in WinPcap API-compatible Mode.
  3. Leave Restrict Npcap driver’s access to Administrators only unchecked. (You can leave this checked, but will need to ensure the overlay then runs in admin mode)
  4. Restart Windows.
  5. Start Spirit Vale Overlay before reproducing the problem.

Spirit Vale Overlay captures passively and does not send, modify, drop, or inject game traffic. Other players’ observed DPS can fall when they move outside capture range.

Check VPNs and network optimizers

VPNs and tools such as ExitLag may move game traffic to an adapter that Npcap is not capturing. Temporarily disable the VPN or optimizer as a test, or follow the known fixes in VPN Issues.

If the computer has several network adapters, confirm that the game and the overlay are using the expected active connection. Virtual-machine, VPN, and tunnel adapters are common sources of capture problems.

Check the firewall

Allow Spirit Vale Overlay on Private networks if Windows Firewall prompts. The app’s frontend and bundled backend communicate locally on 127.0.0.1; do not expose or forward its temporary ports to the internet. Public-network access should not normally be necessary.

The overlay is missing, frozen, or misplaced

Move an unreachable tile by editing overlay.json

If a tile is visible but cannot be clicked or dragged, especially near the bottom or right edge of a high-resolution display, move it closer to the upper-left corner by editing its saved coordinates.

  1. Fully exit Spirit Vale Overlay, including its tray icon. overlay.json cannot be edited while the app is open.
  2. Find overlay.json:
    • Portable release: <extracted folder>\data\settings\overlay.json
    • AppData mode: %APPDATA%\Spirit Vale Overlay\data\settings\overlay.json
  3. Copy overlay.json to overlay.json.backup before editing it.
  4. Open the original file in a text editor and find the tile under the top-level elements object. Tile keys include partyRanking, dpsChart, personalDps, health, mana, characterXp, jobXp, weight, buffs, debuffs, toggles, xpTracker, goldTracker, xpChart, lootToast, minimap, and bossTimers.
  5. Change only that tile’s x and y values to 100. These coordinates are measured from the upper-left corner of the display assigned to the tile.

For example, the existing Party DPS Meter entry should contain values like these after editing (this is only an excerpt; do not replace the whole file with it):

"partyRanking": {
  "enabled": true,
  "opacity": 0.4,
  "x": 100,
  "y": 100,
  "width": 251,
  "height": 425,
  "display": "2560x1600@0,0"
}

Keep the existing display, width, and height values. Save the file without adding comments or removing commas, restart the app, unlock the overlay with Ctrl+Shift+1, and reposition the recovered tile normally. Repeat the coordinate change for any other unreachable tile.

If the app rejects the edited file or the overlay resets unexpectedly, exit the app and restore overlay.json.backup as overlay.json.

Logs and information to include in a bug report

Reproduce the problem once, close the app, and collect the newest relevant files.

For the portable configuration, check:

<extracted folder>\neutralinojs.log
<extracted folder>\neutralino-backend.log
<extracted folder>\data\logs\

For AppData mode, also check:

%APPDATA%\Spirit Vale Overlay\data\logs\

Include:

Review logs before sharing them. Diagnostic logs may contain endpoint addresses and raw game-network payloads.

Where to ask

Developer-only checks

These steps apply only when running from source. The portable release does not require a system Bun installation.

The repository requires Bun 1.4.0 or newer. Verify the active installation with:

bun --version
bun --revision

Then, from the repository root:

bun install
bun run check
bun run dev

If Neutralino’s pinned binaries have not been downloaded yet:

bun run --filter @svoverlay/desktop update

To capture additional packet and transition diagnostics during a short reproduction:

$env:SPIRIT_VALE_DIAGNOSTIC_LOGS = "1"
bun run dev

Disable the environment variable afterward. These diagnostic logs can contain raw network payloads and endpoint addresses.