Skip to content

Commit b15d3e3

Browse files
TerminalGravityTerminalGravity
committed
docs: add TROUBLESHOOTING.md with common setup issues
Covers LanceDB native module errors, embedding model downloads, npx version issues, MCP connection debugging, .preflight/ config detection, semantic search indexing, and memory usage.
1 parent e786aba commit b15d3e3

2 files changed

Lines changed: 189 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
1212
[![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev)
1313
[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
1414

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

1717
</div>
1818

@@ -734,6 +734,12 @@ curl http://localhost:11434/api/embed -d '{"model":"all-minilm","input":"test"}'
734734

735735
---
736736

737+
## Troubleshooting
738+
739+
Having issues? Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for solutions to common problems including LanceDB native module errors, embedding model setup, MCP connection issues, and more.
740+
741+
---
742+
737743
## Contributing
738744

739745
This project is young and there's plenty to do. Check the [issues](https://github.com/TerminalGravity/preflight/issues) — several are tagged `good first issue`.

‎TROUBLESHOOTING.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Troubleshooting
2+
3+
Common issues and fixes for preflight.
4+
5+
---
6+
7+
## LanceDB / Native Module Errors
8+
9+
**Symptom:** `Error: Failed to load native module` or `Cannot find module @lancedb/lancedb-...` on startup.
10+
11+
LanceDB uses platform-specific native binaries (NAPI). If the binary for your OS/arch wasn't downloaded during install, it won't load.
12+
13+
**Fixes:**
14+
15+
1. **Re-install with a clean cache:**
16+
```bash
17+
rm -rf node_modules
18+
npm install
19+
```
20+
21+
2. **Check your platform is supported.** LanceDB ships binaries for:
22+
- macOS: `aarch64-apple-darwin` (Apple Silicon), `x86_64-apple-darwin` (Intel)
23+
- Linux: `x86_64` and `aarch64` (glibc and musl)
24+
- Windows: `x86_64` and `aarch64` (MSVC)
25+
26+
If you're on an unsupported platform (e.g., 32-bit Linux, FreeBSD), LanceDB won't work. Open an issue.
27+
28+
3. **Docker / CI:** Make sure `npm install` runs on the same architecture as your runtime. If you build on x86 and run on ARM (or vice versa), the native module won't match. Use `--platform` in Docker or install inside the container.
29+
30+
4. **Node version:** Requires Node 18+. Older versions may fail to load the NAPI binaries.
31+
32+
---
33+
34+
## Embedding Model Downloads Are Slow / Fail
35+
36+
**Symptom:** First run hangs or times out when preflight tries to generate embeddings.
37+
38+
The default `local` embedding provider uses `@xenova/transformers` which downloads the `all-MiniLM-L6-v2` model (~23MB) on first use. This can be slow on restricted networks.
39+
40+
**Fixes:**
41+
42+
1. **Wait it out.** The first run downloads the model to `~/.cache/xenova/`. Subsequent runs are instant.
43+
44+
2. **Use OpenAI embeddings instead** (faster, but needs an API key):
45+
```yaml
46+
# .preflight/config.yml
47+
embeddings:
48+
provider: openai
49+
# Set OPENAI_API_KEY in your environment
50+
```
51+
52+
3. **Proxy / firewall:** If you're behind a corporate proxy, set `HTTPS_PROXY` so the model can download:
53+
```bash
54+
HTTPS_PROXY=http://proxy:8080 npx preflight-dev-serve
55+
```
56+
57+
4. **Pre-download the model** on a machine with internet access, then copy `~/.cache/xenova/` to the target machine.
58+
59+
---
60+
61+
## `npx preflight-dev-serve` Not Found or Wrong Version
62+
63+
**Symptom:** `npx: command not found` or `preflight-dev-serve: not found` or you get an old version.
64+
65+
**Fixes:**
66+
67+
1. **Clear the npx cache:**
68+
```bash
69+
npx --yes clear-npx-cache
70+
npx -y preflight-dev-serve
71+
```
72+
73+
2. **Pin the version** if npx is pulling something stale:
74+
```bash
75+
npx -y preflight-dev-serve@latest
76+
```
77+
78+
3. **Install globally** to avoid npx issues entirely:
79+
```bash
80+
npm install -g preflight-dev
81+
preflight-dev-serve
82+
```
83+
84+
---
85+
86+
## MCP Server Not Connecting to Claude Code
87+
88+
**Symptom:** You added the MCP config but Claude Code doesn't see preflight tools.
89+
90+
**Fixes:**
91+
92+
1. **Restart Claude Code** after adding the MCP server config. MCP servers are loaded at startup.
93+
94+
2. **Check your `.mcp.json` syntax.** A trailing comma or missing quote breaks JSON silently:
95+
```bash
96+
cat .mcp.json | python3 -m json.tool
97+
```
98+
99+
3. **Verify the server starts manually:**
100+
```bash
101+
npx -y preflight-dev-serve
102+
# Should print: "Preflight MCP server running on stdio"
103+
```
104+
If it errors here, fix that first (see sections above).
105+
106+
4. **Path issues with `node`:** If Claude Code uses a different Node than your shell, the MCP server might fail silently. Set the full path:
107+
```json
108+
{
109+
"mcpServers": {
110+
"preflight": {
111+
"command": "/usr/local/bin/node",
112+
"args": ["/path/to/preflight/dist/serve.js"]
113+
}
114+
}
115+
}
116+
```
117+
118+
---
119+
120+
## `.preflight/` Config Not Being Picked Up
121+
122+
**Symptom:** You created `.preflight/config.yml` but preflight ignores your settings.
123+
124+
**Fixes:**
125+
126+
1. **Check the directory is in your project root** — the same directory where `.mcp.json` lives.
127+
128+
2. **Set `CLAUDE_PROJECT_DIR`** if preflight can't find your project:
129+
```bash
130+
claude mcp add preflight \
131+
-e CLAUDE_PROJECT_DIR=/path/to/your/project \
132+
-- npx -y preflight-dev-serve
133+
```
134+
135+
3. **YAML syntax:** Validate your config:
136+
```bash
137+
python3 -c "import yaml; yaml.safe_load(open('.preflight/config.yml'))"
138+
```
139+
140+
---
141+
142+
## Semantic Search Returns No Results
143+
144+
**Symptom:** `search_timeline` or `search_corrections` returns empty even though you have session history.
145+
146+
**Fixes:**
147+
148+
1. **Index your project first:**
149+
```
150+
Use the `onboard_project` tool in Claude Code, or run:
151+
preflight index /path/to/project
152+
```
153+
Preflight needs to ingest your JSONL session files before search works.
154+
155+
2. **Check the data directory exists:**
156+
```bash
157+
ls ~/.preflight/projects/
158+
```
159+
If empty, nothing has been indexed yet.
160+
161+
3. **Wrong project directory:** Preflight hashes the absolute path to identify projects. If you moved your project or use symlinks, re-index.
162+
163+
---
164+
165+
## High Memory Usage
166+
167+
**Symptom:** Node process uses 500MB+ RAM.
168+
169+
The local embedding model (`@xenova/transformers`) loads into memory. This is normal for the first session but shouldn't grow further.
170+
171+
**Fixes:**
172+
173+
1. **Switch to OpenAI embeddings** — offloads embedding computation to the API, reducing local memory to ~50MB.
174+
175+
2. **Limit search scope** — use `since` and project filters in `search_timeline` to avoid scanning large indices.
176+
177+
---
178+
179+
## Still Stuck?
180+
181+
- Check [GitHub Issues](https://github.com/TerminalGravity/preflight/issues) — someone may have hit the same problem.
182+
- Open a new issue with your OS, Node version (`node -v`), and the full error message.

0 commit comments

Comments
 (0)