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

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 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:

# 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 and 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:

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:

:: 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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}