KBCodeKB
Claude CodeUnverified

Fix Claude Code "Cannot find module './yoga.wasm'" Error (MODULE_NOT_FOUND) on macOS, Vertex AI, and npm Global Installations

Claude Code fails to launch with "Error: Cannot find module './yoga.wasm'" after an auto-update corrupts the global npm installation. The yoga.wasm file is a bundled WebAssembly module used by Claude Code's terminal UI rendering stack. During a botched auto-update, this file is left missing or incomplete, causing a MODULE_NOT_FOUND crash on startup. The issue affects macOS and Linux users with global npm installations, particularly those using Node.js version managers (nvm, nodenv, fnm) and Vertex AI users. The error can appear suddenly after the computer sleeps or after a restart, even if Claude Code was working earlier the same day. Anthropic staff (wolffiex, bcherny) confirmed this is an auto-updater corruption bug. The recommended fix is to reinstall globally (npm install -g @anthropic-ai/claude-code@latest) or migrate to the local installer (claude migrate-installer) which is more reliable against auto-update corruption. Latest Claude Code version as of June 2026: 2.1.177. 39 reactions and 52 comments confirm this is a persistent, recurring issue.

Symptoms

  • Claude Code fails to launch with 'Error: Cannot find module ./yoga.wasm'
  • Error code MODULE_NOT_FOUND with require stack pointing to @anthropic-ai/claude-code/cli.js
  • Occurs suddenly after computer sleep, restart, or auto-update — even when Claude Code worked earlier the same day
  • Affects global npm installations using Node.js version managers (nvm, nodenv, fnm, volta)
  • Particularly common on macOS (both Terminal.app and VS Code terminal) with Vertex AI configuration

Error signatures

Error: Cannot find module './yoga.wasm'
MODULE_NOT_FOUND
Require stack: .../@anthropic-ai/claude-code/cli.js
node:internal/modules/cjs/loader

Possible causes

  • Auto-updater botches a background update, leaving yoga.wasm file missing or corrupted in the global npm package directory
  • Node.js version mismatch: Claude Code was installed under one Node.js version (e.g., v20.11.0) but the shell is now using a different version, causing the require to resolve to the wrong path
  • Partial npm install due to network interruption during auto-update, similar to Bun's ink/yoga-wasm-web packaging issue (oven-sh/bun#15639)
  • Global npm package corruption from concurrent processes (e.g., Claude Code auto-updating while another instance is running)

Solutions

Align Node.js version with installation context (for version manager users: nvm, nodenv, fnm, volta)

risk: lowgithubpublished

The yoga.wasm error can occur when Claude Code was globally installed under one Node.js version but the shell is using a different version. Node.js version managers (nvm, nodenv, fnm, volta) each maintain separate global module trees, so a package installed under Node v20 will not be visible under Node v22.

  1. Step 1: Check current Node.js version: node --version
  2. Step 2: Check which Node.js global tree has Claude Code installed: for v in $(nvm list 2>/dev/null | grep -oP 'v\d+\.\d+\.\d+' || nodenv versions --bare 2>/dev/null); do echo "=== Node $v ==="; npm list -g @anthropic-ai/claude-code --depth=0 2>&1; done
  3. Step 3: Switch to the Node.js version that has Claude Code installed: nvm use <version> or nodenv shell <version> or fnm use <version>
  4. Step 4: If Claude Code is not installed under any Node.js version, install it under your preferred version: npm install -g @anthropic-ai/claude-code@latest

Commands

node --version && which node
npm root -g
npm list -g @anthropic-ai/claude-code --depth=0 2>&1; echo exit=$?

Config examples

# .zshrc: Auto-switch to the Node version that has Claude Code installed
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# Set default Node version for Claude Code
nvm alias default 20

Risks

  • Switching Node.js versions may affect other globally installed packages (eslint, typescript, etc.). Consider installing Claude Code under a dedicated Node.js version or using the local installer (Solution 2) to avoid version conflicts.

Verification

  • Step 1: Run `node --version && npm root -g && npm list -g @anthropic-ai/claude-code --depth=0 2>&1; echo exit=\$?` → expect: consistent Node version, global path, and '@anthropic-ai/claude-code@<version>' listed with exit=0
  • Step 2: Run `ls $(npm root -g)/@anthropic-ai/claude-code/yoga.wasm 2>&1; echo exit=\$?` → expect: file path with exit=0
  • Step 3: Run `claude --version 2>&1; echo exit=\$?` → expect: version number with exit=0
✓ 0 verified✕ 0 failed

Migrate to local installer (permanent fix for auto-update corruption)

risk: lowofficialpublished

Use `claude migrate-installer` to switch from global npm installation to Claude Code's own local installer, which Anthropic staff (wolffiex) recommends as more reliable against auto-update corruption that causes the yoga.wasm file to go missing.

  1. Step 1: First, get Claude Code running again using Solution 1 (Reinstall)
  2. Step 2: Run: claude migrate-installer
  3. Step 3: Follow the prompts to move from the global npm install to the local installer
  4. Step 4: After migration, source your shell config: source ~/.zshrc (or ~/.bashrc, ~/.config/fish/config.fish)
  5. Step 5: Verify the new installer path: which claude

Commands

claude migrate-installer
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null || source ~/.config/fish/config.fish 2>/dev/null
which claude && claude --version 2>&1; echo exit=$?

Risks

  • Migration changes how Claude Code is invoked — verify `which claude` points to the new installer path (typically ~/bin/claude or similar local path, NOT node_modules)
  • May require re-sourcing shell configuration after migration
  • If migration itself fails, fall back to global npm install — the local installer is a convenience, not a requirement

Verification

  • Step 1: Run `which claude` → expect stdout: path NOT containing 'node_modules' (e.g., '/Users/<user>/bin/claude'). If path still shows node_modules, migration did not complete — re-run `claude migrate-installer`
  • Step 2: Run `claude --version 2>&1; echo exit=\$?` → expect stdout: version number, exit=0
  • Step 3: Wait for next auto-update (or check after 24 hours) → run `claude --version` again → expect: version may have incremented, exit=0, no yoga.wasm error. If yoga.wasm error recurs after auto-update, the local installer may also be affected — revert to Solution 1.
✓ 0 verified✕ 0 failed

Reinstall Claude Code globally (fastest fix — resolves 90%+ of yoga.wasm errors)

risk: lowgithubpublished

Manually remove the corrupted global installation and reinstall the latest version (2.1.177 as of June 2026). This replaces all missing files including the bundled yoga.wasm WebAssembly module used by Claude Code's terminal UI rendering stack.

  1. Step 1: Find your global node_modules path: npm root -g
  2. Step 2: Remove the corrupted Claude Code installation: rm -rf $(npm root -g)/@anthropic-ai/claude-code
  3. Step 3: Reinstall the latest version: npm install -g @anthropic-ai/claude-code@latest
  4. Step 4: If using pnpm instead of npm: pnpm uninstall -g @anthropic-ai/claude-code && pnpm install -g @anthropic-ai/claude-code && pnpm approve-builds -g
  5. Step 5: Verify installation: claude --version

Commands

npm root -g
rm -rf $(npm root -g)/@anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest
pnpm uninstall -g @anthropic-ai/claude-code && pnpm install -g @anthropic-ai/claude-code && pnpm approve-builds -g
claude --version 2>&1; echo exit=$?

Risks

  • Loses any local modifications to the Claude Code package (generally none for global installs)
  • If using nvm or similar, ensure you are in the correct Node.js version context before reinstalling — run `node --version && npm root -g` first to confirm

Verification

  • Step 1: Run `claude --version 2>&1; echo exit=\$?` → expect stdout: version number (e.g., '2.1.177'), exit=0. If exit code is non-zero and error says 'Cannot find module ./yoga.wasm', reinstall failed — retry with explicit npm cache clean: `npm cache clean --force && npm install -g @anthropic-ai/claude-code@latest`
  • Step 2: Run `ls $(npm root -g)/@anthropic-ai/claude-code/yoga.wasm 2>&1; echo exit=\$?` → expect stdout: full path to yoga.wasm file, exit=0. If exit=2 (No such file), the reinstall did not restore the file — try `npm install -g @anthropic-ai/claude-code@2.1.177` (explicit latest version) instead of @latest
  • Step 3: Run `claude` to launch interactive session → expect: Claude Code TUI loads successfully. If using Vertex AI: `CLAUDE_CODE_USE_VERTEX=1 claude` → expect: normal startup without MODULE_NOT_FOUND
✓ 0 verified✕ 0 failed

Agent Decision Tree: Diagnose yoga.wasm Missing Module Error

risk: lowagentpublished

Before applying fixes, run these diagnostic commands to determine the root cause and choose the right solution.

  1. Step 1: Check if Claude Code is installed globally: npm list -g @anthropic-ai/claude-code 2>&1; echo exit=$?
  2. IF exit code != 0 → Claude Code is NOT installed in the current Node.js global context. Check other Node.js versions. GOTO Step 2.
  3. IF exit code == 0 → Claude Code IS installed globally. GOTO Step 3.
  4. Step 2: List all Node.js versions and check each: for v in $(nvm list 2>/dev/null | grep -oP 'v\d+\.\d+\.\d+' || nodenv versions --bare 2>/dev/null || echo $NODE_VERSION); do echo "=== Node $v ==="; NODE_VERSION=$v npm list -g @anthropic-ai/claude-code 2>&1; done
  5. Step 3: Check for yoga.wasm file: ls -la $(npm root -g)/@anthropic-ai/claude-code/yoga.wasm 2>&1; echo exit=$?
  6. IF file exists → yoga.wasm is present but possibly corrupted. GOTO Solution 1 (Reinstall).
  7. IF file missing → yoga.wasm is absent. GOTO Solution 1 (Reinstall).
  8. Step 4: Check current Claude Code version: claude --version 2>&1; echo exit=$?
  9. IF exit code != 0 AND error matches 'Cannot find module ./yoga.wasm' → confirmed yoga.wasm issue. GOTO Solution 1.
  10. IF exit code == 0 → Claude Code is working now. Issue was transient or already resolved.

Commands

npm list -g @anthropic-ai/claude-code 2>&1; echo exit=$?
ls -la $(npm root -g)/@anthropic-ai/claude-code/yoga.wasm 2>&1; echo exit=$?
claude --version 2>&1; echo exit=$?
node --version && which node && npm root -g

Verification

  • Step 1: Run `npm list -g @anthropic-ai/claude-code 2>&1; echo exit=\$?` → expect stdout contains '@anthropic-ai/claude-code@' and exit=0, OR '-- empty' and exit=1 (if not installed in this context)
  • Step 2: Run `ls -la $(npm root -g)/@anthropic-ai/claude-code/yoga.wasm 2>&1; echo exit=\$?` → expect: either file details with exit=0 (present) OR 'No such file' with exit=2 (missing)
  • Step 3: Run `claude --version 2>&1; echo exit=\$?` → expect: if exit=0, version printed; if exit!=0, error matches 'Cannot find module ./yoga.wasm'
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "16ed7720-a132-43ee-990c-4bba928cedb7",
  "slug": "fix-claude-code-cannot-find-module-yoga-wasm-error-module-not-found-on-macos-vertex-ai-and-npm-global-installations-3bswj8",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-cannot-find-module-yoga-wasm-error-module-not-found-on-macos-vertex-ai-and-npm-global-installations-3bswj8"
}
← Back to all issuesPowered by CodeKB