Troubleshooting

Start with the limited CLI doctor report from the repository you want to check, then confirm the actual MCP connection with ping:

npx --no-install signalint doctor

A terminal command seems to hang

signalint-mcp is a stdio server, so it waits for MCP input. Only init is specially dispatched by that executable in v1.

Use the other binary for terminal commands:

npx --no-install signalint doctor
npx --no-install signalint check .

Since 1.1.1, signalint-mcp doctor also dispatches the CLI. A bare interactive server launch exits with guidance; a normal MCP client launches stdio with non-TTY pipes.

Node cannot load node:sqlite

Check node --version in the environment your MCP client uses, not only your terminal. Signalint requires Node.js ≥ 22.12.0. An IDE launched before a runtime update may still inherit an older executable or PATH; restart it after updating.

project_not_initialized

The MCP check resolved a project without signalint.config.json:

npx signalint-mcp init

Run this from the correct root, then reconnect. SIGNALINT_ALLOW_UNINITIALIZED=1 is an intentional escape hatch, not the normal setup path.

The agent checks another repository

Call ping and inspect structuredContent.projectRoot. Compare that path with the repository you expect.

• Check for a stale project-level cwd.
• Remove a fixed cwd from a shared user configuration.
• Check SIGNALINT_PROJECT_ROOT for an old repository path.
• Prefer project-scoped setup where the client supports it.

See multiple projects for the safe configuration pattern.

Windows startup fails or closes immediately

For clients launching an npm .cmd shim, use a cmd /c wrapper:

{
  "command": "cmd",
  "args": ["/c", "npx", "--no-install", "signalint-mcp"]
}

Linked packages can also expose a junction path that older builds misidentify. After a project-local installation, bypass the shim with the compiled entry points:

node .\node_modules\signalint-mcp\dist\src\index.js
node .\node_modules\signalint-mcp\dist\src\cli.js doctor

The first command starts the MCP server; the second runs doctor. For an MCP client, use command: "node" and an absolute path to dist/src/index.js in args.

An engine errors or times out

Read engines.<name>.message and the top-level status.

• Install required project-local dependencies and plugins.
• Ensure tsc has a root tsconfig.json.
• Ensure ESLint uses a supported flat configuration.
• Install optional Biome before enabling it.
• Raise a deadline only if the engine legitimately needs more time.

Completed engines’ diagnostics are preserved, but a partial check is not clean. See engines and timeouts.

A project check reports too_many_paths

A single paths: ["."] request can expand to more than 512 candidates and hit the internal resolver limit. Narrow the selected inputs or verify coverage with native tools. Non-JS files count before engine relevance filtering; see scan limits.

TypeScript says a config is missing under src

For a project/CLI check, a directory first target such as src selects src/tsconfig.json, not an automatic fallback to the root. Use . for the default root workflow or select an appropriate explicit config/source file. File checks use a root runner with a separate nearest-config hash probe; see engine selection.

Results appear stale after a change

TypeScript cache state now includes a source-file size/mtime fingerprint under the selected config directory, so some unrequested edits invalidate it. It is not a complete dependency graph: same-size/restored-mtime edits, outside/symlinked/skipped sources, and the nested-config/hash mismatch can still be missed. Use a broader check where appropriate and direct native output for uncertain contexts.

If a configuration source is outside the tracked hashing behavior, stop the MCP server, remove .signalint/cache.sqlite and .signalint/cache/, then reconnect and check again. Build-mode .tsbuildinfo files may exist elsewhere. Preserve session.jsonl if you want to retain loop history. Removing the entire .signalint/ directory clears that history too.

See caching for the exact limitations.

get_issue_detail returns stale

The requested snapshot/reference is unknown, expired or unmatched. Pin the originating checkId: older retained snapshots remain queryable, and 1.2.1 refuses detail requests without a check ID. Do not reuse IDs after switching projects/restarting. Exact/prefix lookup can return multiple issues. get_live_diagnostics can enumerate latest internal/buffered issues, not every historical omitted record. See identity and response limits.

Antigravity reports a legacy configuration

The registry recognizes ~/.gemini/config/mcp_config.json for user setup and .agents/mcp_config.json for project setup. Doctor labels ~/.gemini/antigravity/mcp_config.json as legacy; that is a Signalint label, not proof that your current editor stopped using it.

Confirm the active location in your client’s MCP settings before migrating or removing a Signalint entry. Do not delete an active entry solely because doctor labels its path legacy, or delete a whole file containing other servers. Use the Antigravity guide to keep one active entry.

No engines or no linter available

Since 1.1.0 Signalint no longer installs Oxlint/TypeScript as runtime dependencies. Install the engines your config enables in the intended project, then restart so memoized resolution is refreshed. Read engines and status: all-disabled tasks mean nothing_checked, not a clean scan. Doctor now inspects ESLint too, but missing-package warnings are not necessarily blocking and package metadata is not an engine execution test.

Text diagnostics disappeared

Check the active mcpPayload/SIGNALINT_MCP_PAYLOAD setting. A text-only host cannot expose structured-only diagnostic data; use the default both while diagnosing. With compact keys plus structured mode, text can incorrectly say zero despite a positive structured total. Read the structured fields or avoid that combination; see payload modes.

database is locked

1.2.1 waits up to 5 seconds for SQLite locks. A longer lock can still fail. Avoid long-lived exclusive locks, stop competing processes safely, and retry after contention ends; this is not permission to delete someone else’s active database or server.

stats shows no measurements

Metrics accumulate through MCP checks. Terminal signalint check alone does not add MCP session telemetry. Connect a client, perform checks, then run signalint stats in the same project.

If you are still blocked, include Node version, client, relevant configuration, and engine messages in a GitHub issue. Avoid posting private source code or credentials.

Hook, live-buffer or apply results look inconsistent

• Hook approval can miss grouped errors; post-edit uses default rather than configured engines. Inspect JSON and run an explicit required check.
• Empty LSP ingestion does not clear old buffered records; a batch snapshot and the accumulated live view are different. Use filtered live queries and manage buffer lifecycle in the integration.
• Apply success means writes completed, not that verification passed. Inspect postCheckId, delta.error, introduced diagnostics and the working-tree diff. Discard does not undo applied files.

See hooks, live diagnostics and transaction limits.