# Codacy Guardrails troubleshooting

Use this sequence before reinstalling tools.

## Runtime

```bash
git --version
node --version
npm --version
npx --version
curl --version
```

Confirm the IDE process can see the same executable paths as the interactive shell.

With NVM-managed Node and a desktop client, `npx` may be unavailable. The current Codacy troubleshooting guide recommends installing `@codacy/codacy-mcp` globally and configuring the client with absolute paths to the Node executable and MCP entry point. Verify the installed package before doing this.

## MCP

- Validate JSON syntax and client-specific property names.
- Confirm `CODACY_ACCOUNT_TOKEN` and pinned `CODACY_CLI_VERSION` reach the MCP process without printing their values.
- Restart the MCP server and IDE after configuration changes.
- Confirm agent mode and tool selection are enabled.
- For Copilot Business or Enterprise, confirm organization policy permits MCP servers.
- Run one read-only call before enabling writes.

## Windows

Current Guardrails documentation requires WSL on Windows and limits support to VS Code-based IDEs. Run Git, Node, Codacy CLI, repository tools, and MCP inside the same WSL environment to avoid path and line-ending mismatches.

## Rules and scanners

- Identify whether rules come from repository files, Codacy UI, or the default recommended set.
- Confirm the repository is connected when expecting Cloud rule retrieval.
- Refresh local configuration after Cloud rule changes using the current documented command.
- Verify the language and scanner are currently supported.
- Keep native repository scanners for unsupported stacks.

## Safe recovery

Do not solve startup or analysis failures by disabling rules, deleting Codacy configuration, exposing tokens, or making the MCP server write-capable. Capture logs with secrets redacted and document the exact client, OS, Node, package, CLI, and scanner versions.