Troubleshooting

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

Issue 1 — "no context file found"

Symptom: 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.

bash

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

Symptom: 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.

bash

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

Issue 3 — Token reduction is lower than expected (< 80%)

Symptom: 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 test or generated directories.

bash

# test files
**/*.test.*
**/*.spec.*

# build output
dist/
build/
src/generated/
coverage/

Issue 4 — Context file is stale — VS Code shows grade D or "3d ago"

Symptom: 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 to install a post-commit hook.

bash

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

Issue 5 — Over-budget warning: some files were dropped

Symptom: sigmap --report shows files dropped: N — meaning important files are being cut to stay within the token budget.

Options:

The budget auto-scales to your repo by default (autoMaxTokens: true). If files are still being dropped, the repo is very large. Try the options below.
Switch to "strategy": "per-module" — each module gets its own full budget rather than sharing one pool.
Switch to "strategy": "hot-cold" — recently changed files are always injected; older files are served on demand via MCP.
Raise coverageTarget (default 0.80) closer to 1.0 to push the formula toward a higher budget.
Raise maxTokensHeadroom (default 0.20) to let SigMap use a larger fraction of the model context window.
Add exclusions to .contextignore to remove generated/vendor files from the index.
Run sigmap --report --json to see which files consume the most tokens.

json

{
  "strategy": "per-module"
}

Or to use a larger fixed budget and disable auto-scaling:

json

{
  "autoMaxTokens": false,
  "maxTokens": 12000
}

Issue 6 — MCP server not appearing in tool list

Symptom: 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 to confirm it responds before blaming the editor config.

bash

node /path/to/gen-context.js --version
# sigmap v5.5.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":[...]}}  ← 9 tools

Issue 7 — "gen-context.js not found" in VS Code

Symptom: 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:

json

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

Issue 8 — Secret scan is redacting a false positive

Symptom: 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 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 — Monorepo: context only covers one package

Symptom: 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.
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/.

json

{
  "monorepo": true
}

Issue 10 — Watch mode stops working after sleep or wake

Symptom: 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.

bash

ulimit -n 10000   # raise file watch limit (macOS)
sigmap --watch    # restart the watcher
# [sigmap] watching for changes...

Issue 11 — `ask` returns low coverage

Symptom: sigmap ask works, but coverage is low or the context looks too thin for the task.

Fix: run sigmap validate --query "<same query>" first. If coverage is still low, widen srcDirs, raise the budget, or switch to per-module / hot-cold.

Issue 12 — `judge` reports low support

Symptom: the answer sounds plausible, but judge returns a weak groundedness score.

Fix: regenerate the query context with sigmap ask, then re-run judge against .context/query-context.md. A low score often means the answer drifted beyond the supplied files, not that SigMap itself failed.

Issue 13 — `weights` look wrong

Symptom: ranked files feel over-boosted or a stale file keeps winning.

Fix: inspect sigmap weights, then reset with:

bash

sigmap learn --reset

The learning layer is local-only, so reset is safe and immediate.

Issue 14 — `compare` or `share` numbers look stale

Symptom: the CLI output does not match the latest docs or release notes.

Fix: re-run the benchmark matrix before using compare or share:

bash

node scripts/run-benchmark-matrix.mjs --save --skip-clone

That refreshes the saved JSON reports and the HTML benchmark dashboard together.

Issue 15 — MCP config exists but tools still do not appear

Symptom: the config file looks correct, but Claude Code or Cursor still shows no SigMap tools.

Fix: restart the IDE completely, then test the server manually with tools/list. Editors usually register MCP servers only at startup.

Issue 16 — `--report` shows a low coverage grade but `--health` shows A

Symptom: sigmap --report shows coverage D (30–50%) while sigmap --health shows grade A (100%). The numbers look inconsistent and alarming.

Root cause (pre-v5.5): Before v5.5, --report counted every file found in srcDirs — including package.json, tsconfig.json, README.md, and other non-code files — in the coverage denominator. Those files have no extractor and can never appear in the output, inflating the "missing" count.

Fix: Upgrade to v5.5+ and regenerate:

bash

npm install -g sigmap@latest
sigmap
sigmap --report

After upgrading, --report counts only code files (.ts, .js, .py, .go, etc.) in the denominator and prints a separate (N non-code files skipped) line. The two outputs now answer different questions:

Command	Measures
`--health`	All files in srcDirs accessible (always 100% if srcDirs is correct)
`--report`	Code files that have at least one extractable signature

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.

bash

sigmap --health --json

json

{
  "score": 94,
  "grade": "A",
  "version": "5.5.0",
  "node": "22.11.0",
  "contextFile": true,
  "lastGenerated": "2m ago",
  "tokenReduction": "95.3%"
}

Open an issue at github.com/manojmallick/sigmap/issues. Include your OS, Node.js version, and a brief description of the symptom.

Next steps

CLI reference — every flag with examples and expected output
Config reference — every field in gen-context.config.json with defaults
MCP server setup — wire up sigmap's 9 on-demand MCP tools

Made in Amsterdam, Netherlands 🇳🇱

Troubleshooting ​

Issue 1 — "no context file found" ​

Issue 2 — Copilot or Claude still asks "can you share some files?" ​

Issue 3 — Token reduction is lower than expected (< 80%) ​

Issue 4 — Context file is stale — VS Code shows grade D or "3d ago" ​

Issue 5 — Over-budget warning: some files were dropped ​

Issue 6 — MCP server not appearing in tool list ​

Issue 7 — "gen-context.js not found" in VS Code ​

Issue 8 — Secret scan is redacting a false positive ​

Issue 9 — Monorepo: context only covers one package ​

Issue 10 — Watch mode stops working after sleep or wake ​

Issue 11 — ask returns low coverage ​

Issue 12 — judge reports low support ​

Issue 13 — weights look wrong ​

Issue 14 — compare or share numbers look stale ​

Issue 15 — MCP config exists but tools still do not appear ​

Issue 16 — --report shows a low coverage grade but --health shows A ​

Still stuck? Get more help ​

Next steps ​

Troubleshooting

Issue 1 — "no context file found"

Issue 2 — Copilot or Claude still asks "can you share some files?"

Issue 3 — Token reduction is lower than expected (< 80%)

Issue 4 — Context file is stale — VS Code shows grade D or "3d ago"

Issue 5 — Over-budget warning: some files were dropped

Issue 6 — MCP server not appearing in tool list

Issue 7 — "gen-context.js not found" in VS Code

Issue 8 — Secret scan is redacting a false positive

Issue 9 — Monorepo: context only covers one package

Issue 10 — Watch mode stops working after sleep or wake

Issue 11 — `ask` returns low coverage

Issue 12 — `judge` reports low support

Issue 13 — `weights` look wrong

Issue 14 — `compare` or `share` numbers look stale

Issue 15 — MCP config exists but tools still do not appear

Issue 16 — `--report` shows a low coverage grade but `--health` shows A

Still stuck? Get more help

Next steps