nexu-io-open-design/docs/windows-troubleshooting.md

Windows Troubleshooting Guide

Open Design runs on Windows natively, but the path is less travelled than macOS, Linux, or WSL2. This guide covers the most common errors you will hit on a fresh Windows machine and the exact fix for each.

Tip: If your coding-agent CLIs run inside WSL2, use the dedicated WSL2 setup guide. This guide is for native Windows (PowerShell).

---

Installing the desktop app: "Windows protected your PC"

Symptom

When you run the downloaded installer (for example open-design-0.11.0-win-x64-setup.exe), a blue Windows Defender SmartScreen dialog appears:

Windows protected your PC
Microsoft Defender SmartScreen prevented an unrecognized app from starting.
App:       open-design-x.y.z-win-x64-setup.exe
Publisher: Unknown publisher

The first dialog only shows a Don't run button. The Run anyway button is hidden until you click More info.

Why this happens

This is expected and does not mean the app is unsafe or broken. SmartScreen warns about any installer that is not signed with a code-signing certificate it already recognizes. Open Design ships unsigned Windows builds today, so the installer reports Publisher: Unknown publisher and SmartScreen flags it until a given signed binary builds up download reputation. The warning is about verifying who published the file, not about detecting a threat.

Fix

If you downloaded the installer from an official source, you can proceed:

1. Click More info in the dialog.
2. Click Run anyway.
3. Continue through the installer as normal.

Verify the download first

Only run the installer if you got it from an official source:

• open-design.ai, or
• GitHub Releases on the nexu-io/open-design repository.

Do not run an installer from a mirror, a re-upload, or a link you cannot trace back to one of those two sources. If a release publishes a SHA-256 checksum, you can confirm the file is intact before running it:

Get-FileHash .\open-design-x.y.z-win-x64-setup.exe -Algorithm SHA256

Compare the printed hash against the checksum listed on the release page. They must match exactly.

---

Prerequisites

Tool	Version	How to verify
Node.js	~24	node -v
pnpm	10.33.x	pnpm -v
Git	any recent	git --version

---

1. Node 24 installation

Symptom

node -v returns something older than v24.x.x, or you do not have Node installed at all.

Fix

Option A — nvm-windows (recommended)

1. Install nvm-windows.

2. In a fresh PowerShell window:

   nvm install 24
   nvm use 24
   node -v   # should print v24.x.x
   

Option B — Official installer

Download and run the Node 24 .msi from nodejs.org.

Common nvm-windows gotcha

If running nvm version or node -v pops up a Windows dialog that asks "How do you want to open this file?", a fake nvm file (no extension) has been created in C:\Windows\System32.

Fix: Delete that file, then restart PowerShell.

---

2. pnpm not found

Symptom

pnpm : The term 'pnpm' is not recognized as the name of a cmdlet...

Fix (Corepack — recommended)

The repo pins pnpm@10.33.2 in packageManager. Corepack selects that exact version automatically:

corepack enable
corepack pnpm --version   # should print 10.33.2

Note: If corepack enable fails with EPERM or EACCES (common when Node is installed under C:\Program Files\nodejs), use the npm-global fallback in the next section instead.

Fix (npm global — alternative)

If Corepack is not available:

npm install -g pnpm@10.33.2
pnpm -v   # should print 10.33.2

---

3. Build scripts blocked

Symptom

During pnpm install you see:

Ignored build scripts: better-sqlite3, ...

Later, pnpm tools-dev run web fails with native-module errors.

Fix

pnpm 10 blocks lifecycle scripts by default. Allow the packages that need native compilation:

pnpm approve-builds

Approve any packages that appear in the list (commonly better-sqlite3, electron, and esbuild). Then re-run:

pnpm install

Note: better-sqlite3 may fall back to compiling from source on Windows. If pnpm install hangs or fails on this package, make sure the Visual Studio Build Tools (step 4) are installed before running pnpm install.

---

4. Visual Studio / gyp build errors

Symptom

gyp ERR! find VS could not find Visual Studio

or

error MSB8036: The Windows SDK version was not found

Fix

Install Build Tools for Visual Studio 2022 with the following workloads:

• Desktop development with C++
• MSVC v143 - VS 2022 C++ x64/x86 build tools
• Windows 11 SDK (or Windows 10 SDK if you are on Windows 10)

Download: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

If you see gyp ERR! find Python, verify Python is installed:

python --version   # or py --version

If missing, install Python 3.x from python.org and ensure it's on PATH.

After installing all build tools, open a fresh PowerShell window and re-run pnpm install.

---

5. PowerShell execution policy

Symptom

 cannot be loaded because running scripts is disabled on this system.

Fix

On fresh Windows installs, PowerShell blocks script execution by default:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Restart PowerShell after changing the policy.

---

6. Start the dev server

Symptom

You have completed the steps above but are not sure how to launch the app.

Fix

From the repository root:

pnpm tools-dev run web

Expected output ends with something like:

Open Design dev server ready
  - Local:   http://localhost:17573

The exact port may change; always read the terminal output.

---

Quick diagnostic checklist

Run these commands in PowerShell before opening an issue. Include the output in your report.

node -v
pnpm -v
where.exe pnpm
where.exe node
where.exe opencode
corepack --version
python --version   # or py --version
Get-ExecutionPolicy -List

7. Optional: quick launcher

If you want a double-click entry point on Windows, create a launch.bat file in the repo root with:

@echo off
cd /d %~dp0
corepack pnpm tools-dev run web

That keeps the launcher on the supported pnpm tools-dev run web path while still giving you a one-click start.

---

Optional: OpenCode agent CLI on Windows

OpenCode is one of the local agent CLIs Open Design can drive. If you want to use it:

npm install -g opencode-ai
where.exe opencode   # should show C:\Users\YOUR_USERNAME\AppData\Roaming\npm\opencode.cmd
opencode --version

If Open Design still shows OpenCode as not installed in Settings → Execution mode, click Rescan after confirming the opencode.cmd directory is on your user PATH.