Appendix
C
Troubleshooting and FAQ
Symptom-to-fix tables for the failures readers actually hit
This appendix is the operational safety net for the whole book. Every table is organized symptom to fix: you look up what broke, read why, and apply the fix. The failures here are the ones readers actually hit, drawn from the official QUICKSTART.md, GitHub issue history, and repeated first-run patterns. Ninety percent of them trace back to two causes --- a version pin mismatch or a stopped daemon. Start there every time.
Version pins, command names, and per-CLI MCP configuration paths change with every Open Design release. This appendix reflects Open Design v0.9.0 (released June 2, 2026) and the MCP spec at 2025-11-25. Verify any command or path against the live repository at github.com/nexu-io/open-design before relying on it in a production setup.
C.1 Install and Build Failures
The from-source install requires Node ~24 (enforced in package.json#engines) and pnpm 10.33.x (specifically 10.33.2, auto-selected by Corepack). As of June 2026, the most common first-run failure is a better-sqlite3 native build error --- it accounts for a large share of issues filed in the repository. The fix is almost always a version mismatch or a missing build toolchain.
Before diagnosing anything else, confirm your Node version:
$ node --version # Must output v24.x.x
$ pnpm --version # Must output 10.33.xIf either is wrong, switch to Node 24 using nvm use 24 or fnm use 24, then run corepack enable to let Corepack re-pin pnpm. If you recently switched Node versions and the install was previously working, rebuild the native module before anything else:
$ pnpm --filter @open-design/daemon rebuild better-sqlite3My take: Ninety percent of first-run failures are version pins or a stopped daemon. Before reading the rest of this appendix, run node --version and od status. If those two checks pass, the real problem is almost always in the next section. I've set up Open Design on five different machines; the one that took the longest was the one where I skipped the version check first.
| Symptom | Cause | Fix |
|---|---|---|
Error: NODE_MODULE_VERSION 127 expected, 136 found during pnpm install |
better-sqlite3 binary compiled against a different Node version's V8 headers (ABI mismatch) |
Run pnpm --filter @open-design/daemon rebuild better-sqlite3 after switching to Node 24 via nvm use 24 |
gyp ERR! build error or make: g++: No such file |
Missing C++ build toolchain required to compile better-sqlite3 native module |
macOS: xcode-select --install. Linux: apt-get install build-essential python3. Windows: install Visual Studio Build Tools with the C++ workload |
ERR_PNPM_EXEC_PERMISSIONS_BLOCKED or native script fails under pnpm 10.x |
pnpm 10.x enforces a native script blocklist by default; better-sqlite3 post-install script is blocked |
Ensure you are on pnpm 10.33.x via Corepack (corepack enable); do not manually install a different pnpm major version. If blocked persists, add allowedDeprecatedVersions or check the pnpm release notes for your exact version |
ENGINES_MISMATCH: your Node version does not satisfy ~24 |
Node version outside the pinned range; package.json#engines enforces this |
Install Node 24: nvm install 24 && nvm use 24 or equivalent with fnm. Then re-run corepack enable && pnpm install |
| Docker Compose starts but daemon is unreachable from the host on macOS | macOS Docker Desktop uses bridge networking by default; the daemon inside the container is not exposed to localhost |
Enable host networking in Docker Desktop (Preferences > Resources > Advanced > Enable "Host networking") and add network_mode: host to the compose service. On Linux and Windows native, bridge networking works without this change |
C.2 Daemon and MCP Connection
The daemon runs on localhost:7456 by default and serves the Express API with SSE streaming. If the daemon is not running, the preview stays blank, generations silently fail, and od mcp install may succeed without producing anything useful. Check daemon health before diagnosing anything at the agent or MCP layer.
$ od status
# Or query the health endpoint directly:
$ curl http://localhost:7456/healthMCP (Model Context Protocol) configuration is per-CLI: running od mcp install claude-code writes to Claude Code's config only. If you use multiple agent CLIs --- Claude Code plus OpenCode, for example --- you must run od mcp install for each. As of June 2026, Claude Code stores MCP servers in ~/.claude/settings.json under mcpServers, while OpenCode uses ~/.config/opencode/opencode.jsonc with a root mcp key and type: "stdio".
Never disable the sandbox or expose the daemon port publicly to work around a connection problem. Both the Electron sandbox and the daemon's SSRF protection exist as load-bearing security controls. If an agent can't reach the daemon, the fix is always in the config --- not in loosening the security model. See section 08.1 for the full rationale.
| Symptom | Cause | Fix |
|---|---|---|
| Preview window stays blank; no artifact appears after generation | Daemon is stopped or crashed; SSE stream is not reaching the frontend | Run od status or curl http://localhost:7456/health. If unresponsive, restart: pnpm tools-dev restart. Check stderr for Cannot find module better-sqlite3 or Port 7456 already in use |
od mcp install claude-code succeeds but Claude Code can't see the Open Design tools |
MCP server was written to Claude Code's config but the agent session was not restarted; or the config path is wrong on the current platform | Restart Claude Code after running od mcp install. Verify the entry in ~/.claude/settings.json under mcpServers. On Windows, confirm the path uses the correct drive letter and that the session runs in the same PowerShell or WSL environment where od is on PATH |
OpenCode doesn't recognize Open Design tools after od mcp install opencode |
OpenCode MCP config is in ~/.config/opencode/opencode.jsonc; automatic registration sometimes doesn't update this file |
Open ~/.config/opencode/opencode.jsonc and confirm an entry exists under the mcp key with "type": "stdio" and "command": "od". If missing, add it manually and restart OpenCode |
| Agent is not detected in Settings; "Rescan" button shows nothing | The CLI binary is not on PATH in the environment Open Design scans, or it was installed after Open Design started |
Confirm the CLI is on PATH in the terminal Open Design was launched from. On Windows, ensure the session matches the environment (PowerShell vs WSL) where the CLI was installed. Click "Rescan" in Open Design Settings after confirming |
| Artifact never renders; generation completes but the preview panel is empty | The model didn't wrap its output in <artifact> tags; the streaming artifact parser received raw code instead of a wrapped artifact |
Run the daemon in foreground mode (pnpm tools-dev run daemon) and check stderr for the system prompt and agent output. If tags are missing, explicitly invoke the skill in the prompt: use "Use the web-prototype skill with the Linear brand system to build..." instead of a bare instruction |
C.3 Proxy, Preview, and Export
The BYOK (Bring Your Own Key) proxy routes model calls to Anthropic, OpenAI, Azure, Google, or a local Ollama instance. Misconfigured keys produce 401 or 403 errors that are easily misread as a daemon failure. The proxy also includes SSRF (server-side request forgery) protection that blocks certain private-IP targets --- this is intentional, not a bug.
Preview/export divergence is the other common failure at this layer. The preview uses a sandboxed srcdoc iframe that resolves asset URLs relative to the embedding page. The HTML export inlines content differently. An artifact that looks correct in the preview can break in the exported file when external images or fonts are involved. Always verify the exported file --- not just the preview --- before shipping. This is covered in depth in section 08.6.
HyperFrames renders HTML-to-MP4 via frame capture and encode on your local CPU. As of June 2026, there is no GPU acceleration on most setups. A 15-second animation at 1080p can take several minutes on a mid-tier machine. backdrop-filter: blur effects are particularly expensive --- budget roughly 200ms per frame over 1920×1080. Use draft quality for iteration and full quality only for final renders.
My take: Preview/export divergence is the failure mode I see readers dismiss too quickly. The preview is forgiving --- it runs inside a live browser context where external assets load fine. The exported HTML has to be self-contained, and that's where things break. I test every exported file by opening it with network access disabled. If it breaks, I know immediately instead of finding out after the artifact is in a stakeholder's inbox.
| Symptom | Cause | Fix |
|---|---|---|
| Model calls return 401 or 403; generations fail immediately | BYOK proxy has an invalid, expired, or missing API key for the configured model provider (Anthropic, OpenAI, Azure, or Google) | Verify the key is valid and has the correct permissions for the provider. Check the .env file (or the Settings UI) for the relevant provider key. Confirm the key has not expired or been rotated. |
| BYOK proxy blocks a request with "SSRF protection: private IP blocked" | The proxy's SSRF protection rejected a target URL that resolved to a private IP (e.g., a local Ollama endpoint on an unusual address) | Use localhost or 127.0.0.1 for local Ollama; avoid IP ranges that trigger the blocklist. Do not disable SSRF protection --- it is a load-bearing security control |
| External images load in the preview but are broken or missing in the exported HTML file | srcdoc iframe resolves relative URLs from the embedding page; the HTML inliner uses a different base and cannot fetch external assets at export time |
Use absolute URLs for all external images in the artifact prompt, or ask the agent to inline images as data URIs. Verify the exported file by opening it with network disabled before sharing |
| PDF export produces blank pages or cuts off content | PDF is generated via browser print; fixed-height slides or absolute-positioned elements can cause content to fall outside the printable area | Ask the agent to use a reflowable layout for PDF targets. Check the artifact for overflow: hidden on containers and position: fixed elements --- these are common culprits. |
| HyperFrames render takes more than 10 minutes for a short animation | Frame-capture-plus-encode is CPU-bound; complex CSS effects (especially backdrop-filter: blur) multiply per-frame render time significantly |
Use draft quality during iteration. Remove or reduce backdrop-filter: blur while iterating --- it is the single most expensive CSS effect in HyperFrames renders. Render at full quality only for the final export. Keep iterative clips under 15 seconds |
C.4 Frequently Asked Questions
These are the questions that come up repeatedly once the common failures are resolved. They are not troubleshooting items --- they are conceptual clarifications that affect how you use Open Design day to day.
Is local-first the same as local inference?
No. Local-first means your files, your database, and your orchestration run on your machine. The daemon is local. The .od/ project directory is local. Whether inference is local depends on which model provider you configure. If you use the BYOK proxy to call Anthropic, OpenAI, Azure, or Google, model inference happens in the cloud. Only Ollama keeps inference fully local. Local-first controls where your data and control live --- not where computation happens. Choose a local model if inference privacy is your goal. See Chapter 01 for the full discussion.
Can I use the bundled brand systems for production work?
The 150 bundled brand systems are reference materials for learning the DESIGN.md schema and for prototyping. They are identified nominatively --- using names like Linear or Stripe to describe the system's inspiration. They are not a license to ship artifacts that reproduce those companies' trademarked identities. Use the bundled systems to learn structure, then author your own DESIGN.md for production work. Chapter 05 covers this in detail.
Which agent CLI should I use?
As of June 2026, Open Design supports 21 coding-agent CLIs. For most readers, Claude Code is the default: it has the most complete MCP integration and the most thoroughly tested skill-invocation behavior. OpenCode (MIT license) is the right choice if vendor independence is a priority. Cursor works well for teams already in that ecosystem. The comparison in Chapter 11 covers all criteria in depth. Don't pick based on what's most familiar --- pick based on the constraint that matters most for your project: privacy, license, or team fit.
What is the Apache-2.0 license for Open Design, and can I use it commercially?
Open Design is licensed under Apache-2.0, which permits commercial use, modification, distribution, and private use, subject to including the license and notice files in any distribution. It does not grant trademark rights. Using Open Design commercially to generate artifacts for clients is permitted; shipping a product that reproduces a bundled brand system's trademarked identity is not.
How do I keep my skills and plugins up to date?
Skills, brand systems, and plugins ship with the Open Design repository. When a new version releases, pull the latest from the repository (git pull origin main) and re-run pnpm install. If you have authored custom skills or plugins, they live in your project directory and are not overwritten by upstream updates. If you have forked a bundled skill, you will need to merge upstream changes manually --- this is why Chapter 04 recommends layering on top of bundled skills rather than forking them outright.
Next: This is the final appendix. For the full architectural context behind these failure modes, return to Chapter 02 (install and architecture), Chapter 08 (the preview and export pipeline), and Chapter 10 (the MCP server). For the skills and brand systems referenced in C.4, see Appendix B.