Troubleshooting
Find your symptom. If it is not here, the last ten lines of the output are the useful part, and an issue with them is genuinely more useful to us than a success report.
Common failures
| What happened | Why | What to do |
|---|---|---|
command not found after installing | The install worked, but the folder it went into is not on your PATH. | Open a brand-new terminal and try again — the shell caches its path list. If it still fails, python3 -m mcpgawk always works, and tells you the package is fine and only the shortcut is missing. |
| It sits there for minutes | A local server is slow to start, usually a first-run npx download. | Give it up to three minutes, then Ctrl-C. Scanning launches local servers, so the slowest server sets the pace. |
| It found no servers at all | Either you genuinely have none configured, or discovery could not read the configs. | Run mcpgawk status. It names every client it looked at and what it found there, including the ones it could not read — so the two cases are distinguishable. |
| It found fewer servers than you have | A config in a location or format discovery does not yet read. | Check the Clients page for the path it reads for that client. A missing client is a real defect and worth reporting. |
| A server says it needs sign-in | It is an authenticated remote server and has not been signed into from this machine. | mcpgawk scan --login. Note it is reported as unscanned, not clean — an unscanned server is never counted as safe. |
| The panel opens but the buttons do nothing | You opened the bare URL rather than the tokened link. | That is deliberate. Action buttons only work through the link printed in your terminal, so a bookmark — or an agent that opens the page — cannot drive the machine. Restart mcpgawk panel and use the fresh link. |
| A command exits 3 | Either the capability is not installed, or it belongs to the paid tier. | Exit 3 is always "cannot run", never "ran and found nothing". The message says which. |
| It crashed with a wall of red | An unhandled error. | The last ten lines are the useful part. The guard hook is built to never do this to your agent: if it fails internally it defers and says so, rather than turning its own bug into a verdict. |
Every state a server can be in
Nine states, and none of them means "probably fine".
| State | Means | What to do |
|---|---|---|
CLEAN | Scanned, nothing to act on. | Nothing. This is the good one. |
REVIEW | Scanned, and something is worth your eyes — a tool that can write or reach the network. | Open the Findings tab, or mcpgawk scan --detail. A finding is a signal, not a verdict. |
AUTH | The server needs a browser sign-in before it will answer. | Run mcpgawk scan --login, or sign in from the panel. Until then it is unscanned, and it is counted as unscanned rather than clean. |
UNREACHABLE | It is configured, but nothing answers — usually the program it launches is gone. | Check the command in your agent's config still exists. A stale entry left behind by an uninstall is the common cause. |
TIMED-OUT | It started but did not answer in time. | Try again; a cold npx download is slow the first time. If it repeats, the server is hanging on start. |
FAILED | It started and errored. | The message carries the server's own words. That text is the server's, not ours. |
SKIPPED | A local server was found but not launched, because launching it runs its code. | Re-run with --yes if you want it launched. Consent is asked once, and a non-interactive run always defaults to deny. |
NOT-SCANNABLE | It runs outside this machine — an account-hosted connector with no local endpoint. | Nothing to do. It is listed rather than hidden so the fleet count is not read as everything you have. |
INCOMPLETE | It ran but could not finish. | Treat as unknown, never as clean. This is why the exit code is 4 and not 0. |
Exit codes
| Code | Means | Read it as |
|---|---|---|
0 | clean | nothing to act on |
1 | findings | something was found and is reported |
2 | usage | the command was called wrongly |
3 | cannot run | not installed, or the capability is not on this tier |
4 | incomplete | it ran but could not finish, so it is NOT clean |
When the guard itself fails
A pre-execution hook that crashes could block every tool call your agent makes. It is built so that cannot happen: the hook always exits 0 on its own internal error and says so on stderr, rather than turning its own bug into a verdict. A denial is expressed in the documented channel only, never as an accident.
The consequence is honest and worth knowing: if the hook cannot decide, the call goes
through and is recorded as not checked. That is why mcpgawk status reports
checked and not-checked counts separately instead of one reassuring number.