Common fixes

# Troubleshooting

Most issues resolve in under a minute. Start with the first section that matches your symptom.

Issue 1

🔴
Issue 1 of 10
"no context file found"
VS Code shows "no context", the MCP server returns an error, or Copilot doesn't know anything about your codebase.
Fix

- The context file must be generated before anything can read it. Run `sigmap` or `node gen-context.js` to create it.
- Check your Node.js version — v18 or later is required. Run `node --version` to confirm.

terminal
$ node --version
v22.11.0 ← v18+ required
$ sigmap && ls .github/copilot-instructions.md
[sigmap] ✓ wrote .github/copilot-instructions.md
.github/copilot-instructions.md ← file now exists

Issue 2

🟡
Issue 2 of 10
Copilot or Claude still asks "can you share some files?"
The AI doesn't appear to know your codebase structure even though the context file was generated.
Fix

- The file must be at exactly `.github/copilot-instructions.md` in the workspace root — not a subdirectory. Verify: `ls .github/copilot-instructions.md`
- For Claude Code: also commit `CLAUDE.md` by adding `"claude"` to the `outputs` array in your config, then rerun.
- Restart the IDE after generating for the first time — some editors only read the file at startup.

terminal
$ ls .github/copilot-instructions.md
.github/copilot-instructions.md ← must exist here

Issue 3

🟡
Issue 3 of 10
Token reduction is lower than expected (< 80%)
`sigmap --report` shows only 60–70% reduction instead of the typical 90–97%.
Cause

- You are likely indexing test files, `dist/`, `build/` output, or generated code — these contain many signatures that add bulk without adding information.

Fix

- Run `sigmap --init` to generate a starter `.contextignore`, then add exclusions for any test or generated directories in your project.

.contextignore
# test files
**/*.test.*
**/*.spec.*
# build output
dist/
build/
src/generated/
coverage/

Issue 4

🟡
Issue 4 of 10
Context file is stale — VS Code shows grade D or "3d ago"
The status bar shows a low grade or a large "last updated" timestamp, meaning the context no longer matches current code.
Fix

- Click the status bar item to trigger a manual regeneration from within VS Code.
- For automatic freshness on every commit, run `sigmap --setup` once. It installs a `.git/hooks/post-commit` hook that regenerates context automatically.

terminal
$ sigmap --setup
[sigmap] ✓ installed .git/hooks/post-commit
[sigmap] context will regenerate on every git commit

Issue 5

🟡
Issue 5 of 10
Over-budget warning: some files were dropped
`sigmap --report` shows `files dropped: N` — meaning important files are being cut to stay within the token budget.
Options

- Raise `maxTokens` in `gen-context.config.json` (e.g. `8000` or `10000`) to give the budget more headroom.
- Add more exclusions to `.contextignore` to remove low-value files from the index.
- Switch to `"strategy": "per-module"` or `"strategy": "hot-cold"` to load only the relevant portion of the codebase.
- Run `sigmap --report --json` to see which specific files are consuming the most tokens, then target those first.

gen-context.config.json
{
"maxTokens": 10000, ← raise from default 6000
"strategy": "hot-cold" ← or switch strategy
}

Issue 6

🔴
Issue 6 of 10
MCP server not appearing in tool list
Claude Code or Cursor doesn't show any sigmap tools, or `tools/list` returns an empty array.
Fix

- Verify the absolute path resolves: run `node /path/to/gen-context.js --version` in a terminal. If it errors, the path is wrong.
- Check JSON syntax in the settings file — a missing comma or mismatched quote will silently prevent parsing.
- Reload or fully restart the IDE after making config changes. MCP servers are registered at startup.
- Test the server manually with the command below to confirm it responds before blaming the editor config.

terminal — manual test
$ node /path/to/gen-context.js --version
sigmap v2.8.0 ← must print a version
$ echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}} ← 8 tools

Issue 7

🟡
Issue 7 of 10
"gen-context.js not found" in VS Code
The VS Code extension shows an error and can't regenerate the context file.
Fix

- Install globally so the extension can find it anywhere: `npm install -g sigmap`
- Or set the explicit path in VS Code settings using the `sigmap.scriptPath` option shown below.

.vscode/settings.json
{
"sigmap.scriptPath": "${workspaceFolder}/gen-context.js"
}

Issue 8

🟡
Issue 8 of 10
Secret scan is redacting a false positive
A variable name that happens to match a secret pattern appears as `[REDACTED]` in the output.
Fix

- Add a `.contextignore` rule to exclude that specific file from the index entirely.
- Alternatively, set `"secretScan": false` in your config — but only do this if you are certain there are no real secrets in your source directories.

🔍
The 10 secret patterns checked
AWS Access Key, AWS Secret Key, GCP API Key, GitHub Token (`ghp_` / `gho_`), JWT (`eyJ...`), database connection string, SSH private key header, Stripe key (`sk_live_`), Twilio key, generic `password` / `api_key` assignments in code.

Issue 9

🟡
Issue 9 of 10
Monorepo: context only covers one package
Only one package's signatures appear in the output even though your repo has multiple packages under `packages/` or `apps/`.
Fix

- Enable monorepo mode in `gen-context.config.json`: set `"monorepo": true`. SigMap will then generate a separate context section per package.
- Or run `sigmap --monorepo` as a one-off flag without touching the config file.
- Make sure your package directories use one of the standard names: `packages/`, `apps/`, or `services/`.

gen-context.config.json
{
"monorepo": true
}

Issue 10

🟡
Issue 10 of 10
Watch mode stops working after sleep or wake
`sigmap --watch` was running fine, but after the machine slept and woke, file changes are no longer picked up.
Fix

- Restart the watcher process. This is an OS-level file descriptor limit issue that affects some macOS and Linux systems after sleep cycles.
- On macOS, increase the file watch limit for the current session: `ulimit -n 10000`
- For a more reliable alternative, use the git hook approach via `sigmap --setup` — it regenerates on every commit and is not affected by sleep/wake cycles.

terminal — macOS fix
$ ulimit -n 10000 ← raise file watch limit
$ sigmap --watch ← restart the watcher
[sigmap] watching for changes...

Still stuck?

## Get more help

Run the health check and share the output in a GitHub issue — it includes everything needed to diagnose the problem.

terminal
$ sigmap --health --json
{
"score": 94,
"grade": "A",
"version": "2.4.0",
"node": "22.11.0",
"contextFile": true,
"lastGenerated": "2m ago",
"tokenReduction": "95.3%"
}
🐛
Open a GitHub issue
Share the output of `sigmap --health --json` at github.com/manojmallick/sigmap/issues. Include your OS, Node.js version, and a brief description of the symptom.

What's next

## Explore further

All flags
CLI reference
Every flag sigmap accepts, with examples and expected output for each one.
All options
Config reference
Every field in gen-context.config.json with defaults, types, and examples.
8 tools
MCP server setup
Wire up sigmap's 8 on-demand MCP tools for Claude Code, Cursor, and Windsurf.