# Common Troubleshooting Steps for Wand Enhancer: Network, Patching, and Runtime Fixes

> Troubleshoot Wand Enhancer network, patching, and runtime errors. Fix firewall blocks, locked ASAR files, and script execution issues for smoother operation.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: how-to-guide
- Published: 2026-07-13

---

**Most Wand Enhancer issues stem from network firewall blocks on TCP 3223, locked ASAR files during patching, or unguarded custom scripts that execute twice.**

Wand Enhancer is a local‑only patcher that injects a remote‑control web panel into the Wand client. When troubleshooting this open‑source tool from the **k1tbyte/Wand‑Enhancer** repository, most failures fall into three categories: **network connectivity**, **ASAR extraction**, and **custom script runtime errors**.

## Remote Web Panel Connectivity Issues

The remote web panel, served by [`web-panel/bridge/src/index.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/index.ts) and compiled to `web-panel/dist/bridge.cjs`, runs an Express server on **TCP 3223**. If the mobile UI cannot reach your PC, the connection typically fails at the network or firewall level.

### Verifying LAN and Firewall Settings

First, ensure both your PC and mobile device share the **same LAN**. Router‑level client isolation blocks inter‑device traffic, so verify your network profile is set to **Private** rather than Public. Then open Windows Firewall and create an inbound rule for TCP 3223:

```powershell

# Verify existing rules for port 3223

Get-NetFirewallRule -DisplayName "*3223*" | Format-Table -AutoSize

# Add a new inbound rule if missing

New-NetFirewallRule -DisplayName "Wand Enhancer Remote Panel" `
    -Direction Inbound -Protocol TCP -LocalPort 3223 -Action Allow `
    -Profile Private

```

### Port Configuration and VPN Tunneling

If you need remote access outside your local network (over cellular or different Wi‑Fi), tunnel the port using a VPN solution like **Tailscale**. The bridge does not bind to external interfaces by default, so direct WAN access requires either VPN tunneling or manual port forwarding with appropriate security measures.

## ASAR Extraction and Patching Failures

The patching logic resides in [`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs) and [`AsarSharp/AsarCreator.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarCreator.cs), which extract `resources/app.asar` from the Wand client, inject `web-panel/dist/` files, and repackage the archive.

### Handling Locked Files and Backup Verification

The most common extraction failure occurs when **Wand is running** while the patcher operates, locking the `app.asar` file. Always close the Wand client before patching. After successful patching, verify that backup files `app.asar.backup` and `app.asar.unpacked.backup` exist in the resources directory. If the patcher reports "file locked" or "missing entry," terminate any lingering Wand processes and retry.

### Unpacked Entries Handling

The extractor intentionally **skips unpacked entries** where the source equals the destination, silently ignoring missing unpacked files. This behavior is normal and prevents infinite loops. If you require those specific unpacked files, restore them manually from the original Wand installation before running the patcher.

## Custom JavaScript Injection Errors

User scripts placed in the `renderer-scripts/` folder execute inside Wand’s renderer process with full DOM and Node `require` access. These scripts run through the `WandEnhancer` helper API.

### Preventing Double Execution with Guard Flags

Scripts may execute **twice**—once on initial load and again shortly after. To prevent duplicate initialization or conflicting DOM manipulations, wrap your code with a guard flag:

```javascript
if (!globalThis.__myCustomScriptInstalled) {
  globalThis.__myCustomScriptInstalled = true;
  WandEnhancer.log('My custom script loaded', WandEnhancer.remoteUrl);
  // Your DOM-manipulating code here
}

```

### Logging and Error Handling

Use the provided `WandEnhancer.log(...)` API to surface diagnostic information. Unlike raw console calls, this method captures errors without crashing the Wand client, allowing you to inspect issues in the DevTools console (press **F12**) or the log file adjacent to `WandEnhancer.exe`.

## Build and Compilation Problems

Compiling from source requires the native helper in `tools/asar-fuses-bypass/`, the web panel build (Vite/TypeScript), and .NET Framework dependencies.

### Prerequisites and Environment Setup

Install the exact prerequisites listed in the repository documentation: **CMake**, **pnpm**, **Visual Studio 2022 Build Tools**, and **.NET Framework 4.8**. Run `build.cmd` from an elevated **Developer Command Prompt** so MSBuild can locate the required SDKs:

```cmd
:: Run the full build after fixing missing prerequisites
build.cmd

```

Missing CMake or Node components typically manifest as MSBuild errors during the native helper compilation phase.

## Security and SmartScreen Warnings

The generated `WandEnhancer.exe` is unsigned and may trigger Windows Defender or SmartScreen alerts. This warning is expected for self‑built binaries. Verify the source code and GitHub Actions logs that produced your artifact before bypassing the warning. To permanently suppress the warning, you must code‑sign the binary yourself, which is outside the scope of the open‑source project.

## Diagnostic Commands and Validation

When standard fixes fail, use these diagnostic steps:

1. **Open the console** in the Remote Web Panel (press **F12**) and inspect network errors or JavaScript exceptions.

2. **Check the log file** created next to `WandEnhancer.exe` (named `WandEnhancer.log`). It records each extraction step and caught script errors.

3. **Run the built‑in validator** `scripts/validate-release-metadata.ps1` to ensure the patched ASAR matches the expected structure.

4. **Test port reachability** using `telnet <PC-IP> 3223` or temporarily disable third‑party firewalls/antivirus to isolate conflicts.

## Summary

- **Network issues**: Ensure TCP 3223 is allowed in Windows Firewall, set your network to Private, and use Tailscale for remote access.
- **Patching failures**: Close Wand before patching, verify backup files exist, and understand that unpacked entries are skipped by design in [`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs).
- **Script errors**: Guard against double execution with `globalThis` flags and use `WandEnhancer.log()` for safe error reporting.
- **Build problems**: Install CMake, pnpm, VS 2022 Build Tools, and run `build.cmd` from an elevated Developer Command Prompt.
- **Diagnostics**: Use the F12 console, `WandEnhancer.log`, and `scripts/validate-release-metadata.ps1` to verify installation integrity.

## Frequently Asked Questions

### Why does the Remote Web Panel fail to load on my mobile device?

The panel requires both devices to share the same LAN and for Windows Firewall to allow inbound TCP 3223 traffic. Check that your network profile is set to Private, not Public, and verify the port is open using PowerShell or `telnet`. For access outside your local network, use a VPN like Tailscale to tunnel the connection.

### Why do I get "file locked" errors when patching the Wand client?

The [`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs) component cannot modify `resources/app.asar` while the Wand process is running. Ensure Wand is completely closed before running the patcher. If the error persists, check for background Wand processes in Task Manager and terminate them before retrying the extraction.

### Why does my custom script run twice or crash the UI?

Scripts in the `renderer-scripts/` folder execute twice during the Wand lifecycle (on load and shortly after). Wrap your initialization code with a guard flag like `if (!globalThis.__myScriptInstalled)` to prevent duplicate execution. Always use `WandEnhancer.log()` instead of raw console methods to avoid uncaught exceptions that can freeze the UI.

### How do I verify that the patcher created a valid installation?

Run the `scripts/validate-release-metadata.ps1` PowerShell script to check the ASAR structure against expected metadata. Additionally, confirm that `app.asar.backup` and `app.asar.unpacked.backup` exist in the Wand resources directory, and inspect `WandEnhancer.log` for extraction success messages.