Skip to content

fix: correct Node version badge (18+ → 20+) and add troubleshooting entry #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TerminalGravity wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: correct Node version badge (18+ → 20+) and add troubleshooting entry #244

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
[![MCP](https://img.shields.io/badge/MCP-Compatible-blueviolet)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev)
[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
[![Node 20+](https://img.shields.io/badge/node-20%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)

Expand Down Expand Up @@ -662,6 +662,16 @@ node --version

On Apple Silicon Macs, make sure you're running a native arm64 Node — not Rosetta. Check with `node -e "console.log(process.arch)"` (should print `arm64`).

### Crashes or syntax errors on Node 18 or 19

Preflight requires **Node 20+**. On Node 18/19 you may see cryptic errors like `SyntaxError: Unexpected token` or failed native module loads because preflight uses Node 20 features (built-in `fetch`, `import.meta.resolve`, native test runner in CI). Check your version:

```bash
node --version # Must be v20.x or higher
```

If you're on 18, upgrade via [nvm](https://github.com/nvm-sh/nvm): `nvm install 20 && nvm use 20`.

### First run is slow (~90MB model download)

The local embedding provider ([Xenova/all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2)) downloads a ~90MB model on first use. This is a one-time cost — subsequent runs use the cached model. If the download hangs behind a corporate proxy, switch to OpenAI embeddings:
Expand Down
Loading