[Introduction](https://verity.md/docs) [Quickstart](https://verity.md/docs/quickstart) [Authentication](https://verity.md/docs/authentication) [How it works](https://verity.md/docs/how-it-works) [Moments](https://verity.md/docs/moments) [Formal verification](https://verity.md/docs/formal) [Findings & verdicts](https://verity.md/docs/findings) [The Standard](https://verity.md/docs/standard) [Org Standards](https://verity.md/docs/org-standards) [Standards on the web](https://verity.md/docs/web-standards) [The terminal editor](https://verity.md/docs/terminal-editor) [Memory](https://verity.md/docs/memory) [Org knowledge](https://verity.md/docs/org-knowledge) [Token telemetry & cost](https://verity.md/docs/cost) [The dashboard](https://verity.md/docs/dashboard) [CLI & commands](https://verity.md/docs/cli) [Files & configuration](https://verity.md/docs/files) [Security & privacy](https://verity.md/docs/security) [Troubleshooting](https://verity.md/docs/troubleshooting)

Reference

# Troubleshooting

Organized by what you see. Two commands answer most of it: verity status says what Verity thinks the situation is, and .verity/.logs/stderr.log says what it said and saw on every run.

Start here

`verity status` prints your account, the Standard version, the active moments, any housekeeping declaration, the `.verityignore` rules, and the findings still open — in that order, because the first three explain most surprises. `verity hooks check` shows what is wired. `.verity/.logs/stderr.log` is what to attach when you write to us.

## Install and setup

### `/plugin marketplace add` is refused

```
Cannot add marketplace "codacy": its network source differs from the one
declared for it in settings (kind, target, or a fetch-shaping field such as
headers / ref / path / sparsePaths)
```

Marketplace names are a single flat namespace on your machine — there is no per-org scoping — so the name is already taken by something pointing somewhere else, and Claude Code will not redefine it. Two common causes:

- **You have Codacy's skills marketplace.** It is named `codacy`, and so was Verity's up to 0.32.1. Verity moved to `verity` in 0.32.2, so an up-to-date install line no longer collides — check you are using `/plugin install verity@verity`.
- **You added the same name from a different source before** — a local directory, or a URL rather than `owner/repo`. A different source *kind* for the same tree is enough to trigger this.

The declaration in `~/.claude/settings.json` is the authoritative one, so removing the marketplace alone can leave it to reassert on the next start. Remove the entry from `extraKnownMarketplaces` there, restart Claude Code, and add it again:

```
# see who holds the name, and where it is declared
verity doctor
cat ~/.claude/plugins/known_marketplaces.json
```

`verity doctor` names the file and the conflicting source, and prints the commands to run. If you have no CLI yet, the two files above tell you the same thing.

### The plugin installed, but nothing reviews my work

Restart Claude Code first — hooks are read at startup. Then, in the project, check what is actually wired:

```
verity hooks check     # says "wired by the Verity Claude Code plugin" when the plugin owns them
verity doctor          # prerequisites, Standard, analysis config, and what to do next
```

If the gate is wired but gating nothing at commit or push, the moments live in the project rather than in the plugin — the plugin's hooks are the same for everyone, so the selection cannot come from them. Set it with `verity config moments turn,commit,push`, and see [Moments](https://verity.md/docs/moments). Errors from the plugin itself show under `/plugin` → **Errors**, tagged `[verity-plugin]`.

### `npm install -g` fails with EACCES

Your npm global directory is not writable. Give npm one you own:

```
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
npm install -g @codacy/verity-cli
```

### The analysis CLI is missing

`@codacy/analysis-cli` comes with Verity, so you do not install it. `verity doctor` names the copy Verity runs, and marks a global copy `not used`: updating that global copy changes nothing. If doctor says the analysis CLI is not found, the Verity install is broken. Reinstall Verity, which includes it:

```
npm install -g @codacy/verity-cli
```

### `verity init` ends with “Not finished”

Init could not set up a usable Standard, so it exits with code 1. Scripts and `/verity:init` stop there. The `Not finished:` line says which case it is:

- **“the Verity service did not answer”** — init could not ask whether your team has a Standard, so it wrote none. If the team has one, reviews still use it. Run `verity init` again once the service answers.
- **“the team's Standard could not be written on this machine”** — reviews still use the team's Standard on the service. Fix the error init printed above, then run it again.
- **“no Standard was written, so the gate cannot review”** — the lines above name the cause. A common one: `.verity/standard.yaml` is not valid YAML, or the service would refuse it, and the service has no Standard either. Init leaves the file as it is. Fix it, or delete it, then run `verity init` again.

When the file is broken but your team has a Standard on the service, init finishes, and reviews use the team's. To replace your file with it: `verity standard pull`.

### `git status` shows `.codacy/` deleted after `verity init`

Verity no longer reads or writes `.codacy/`: static analysis is Trivy only, configured in `.verity/static-analysis.json`. When a re-run of init can prove an older Verity wrote the `.codacy/` config, it removes it with `git rm` and stages the removal. It does not ask first. Commit the removal, or keep the files:

```
git restore --staged --worktree .codacy
```

Codacy's own tools use the same folder. So a `.codacy/` config that Verity cannot prove it wrote stays as it is.

### Windows

Verity runs on Windows, with the plugin or the global CLI. Claude Code runs Verity's hooks in Git Bash when [Git for Windows](https://git-scm.com/downloads/win) is installed, and in PowerShell when it is not. Both work.

- **No console windows.** From CLI 0.36.0, the hooks open no console windows: every process that the CLI or the plugin launcher starts is hidden, and git commands run without a shell. The browser for sign-in still opens normally. If a console window opens at each hook, update the plugin or the CLI to 0.36.0 or later.
- **Static analysis does not run on Windows.** Trivy does not run there, so a review has no static findings. `verity doctor` says so: “Trivy does not run on Windows, so static analysis is off on this machine. The AI review is unchanged.” Nothing needs fixing on your side.
- **PowerShell splits a comma list.** It passes `commit,push` to Verity as two words, `commit push`, and Verity reads only the first. Put the list in quotes: ``` verity config moments "commit,push" ```

### Linux

Not supported yet.

### I am migrating from GATE.md

`verity init` detects a legacy `.gate/` directory and migrates it. You can also run `verity migrate` directly; it is safe to re-run. Then `npm rm -g @codacy/gate-cli`.

## Signing in and access

### Verity says my login expired or was revoked

A login is a 90-day session, so this is its ordinary end of life. Sign back in with `verity login`. If you did not expect it, `verity sessions list` shows whether it was revoked from another machine.

### “This repository is NOT covered by your grants”

Grants come from your last login and only cover repositories where the Verity app is installed. In order:

1. **Was the repository added or granted since your last login?** Re-run `verity login` to refresh the snapshot.
2. **Is the app installed on that account?** `verity login` prints a targeted install link when it is not. Install, then log in again.
3. **Is `origin` a URL Verity can resolve?** An ssh alias like `gh:owner/repo` is not. `git remote set-url origin <full url>`.

### Reviews run, but nothing is recorded

That is the signed-out path, or an uncovered repository (above), or a verification that aged out — `verity status` names which. In every case the fix is `verity login`, not a permission request. `verity status` saying `Anonymous` means no user-bound credential resolved here.

### Verity refused to send my token to a service URL

Credentials are pinned to the service that issued them, so a URL configured in the repository cannot redirect your token. If it is your own backend, name it explicitly with `--service-url` or `VERITY_SERVICE_URL` — that is treated as your intent. An older credential that does not record its issuer is re-issued by `verity login`.

### I signed in on the web and the dashboard is empty

The dashboard shows what the CLI records, so signing in before `verity init` has run in any repository shows the terminal steps instead. Run them, then **check now**; the page also re-checks on its own. If it still finds nothing: an unfinished step, a different GitHub account in the terminal, or a sign-in that predates the app install — sign in again.

### CI cannot authenticate

Do not put a personal login in a pipeline. Mint a service token from inside the repository and store it as a `VERITY_TOKEN` secret:

```
verity token create --name github-actions
```

## The gate

### Nothing runs when my agent stops

```
verity doctor                              # what is set up, what is missing, what to run
verity hooks check
verity config moments                      # which moments are on
verity config moments turn,commit,push     # turn all three on
```

Claude Code reads hooks at startup — restart it after `verity init`, `verity config moments` or `verity hooks install`. If you set the moments to `commit,push`, silence on a turn is the configuration working.

### The commit or push gate did not fire

It fires only on the *agent's* `git commit` / `git push` / `gh pr create` inside Claude Code — not on commands you run yourself — and only for the moments you selected. It also steps aside, loudly, when it cannot tell which tree a command targets (`--git-dir`, `GIT_WORK_TREE=`, two pushes in one command): it allows the command without a review rather than guess.

### A turn was skipped

Verity reviews **the code your agent authored this turn**, and within that, what changed since the last verdict. It also debounces runs within 30 seconds, skips a bare acknowledgment with no code, skips a turn where you typed a `! command` and nothing else acted, and honours a housekeeping declaration. Work you did by hand, a formatter's sweep, and files byte-identical to something already judged do not trigger a review — deliberately. To review anything else, ask: `/verity-analyze` has no such scoping.

### Verity went quiet

`verity status` first — an active `verity ignore` declaration prints before anything else, and so does the `.verityignore` ruleset. Then `verity hooks check`.

### I got a WARN with no findings

The coverage rule: something in the change did not reach the reviewer — a file type that is not reviewed, an oversized file, a truncated budget, an unreachable service, an offline fallback. Rather than claim a clean review it did not perform, Verity downgrades `PASS` to `WARN` and names what it skipped in the scope line. Nothing is blocked.

### “Static analysis stopped after 45 s”

```
Static analysis stopped after 45 s, so it did not run for this review. The first run on a machine downloads Trivy and its database: the download goes on in the background.
```

The first static analysis on a machine downloads Trivy and its vulnerability database, about 1.5 GB on disk. `verity init` starts that download in the background, but a machine that upgraded without a re-run of init downloads it during a review. A review waits at most 45 seconds for the analyzer, then goes on without static findings. The download continues in the background, and a later review runs Trivy as usual. Nothing needs fixing. To start the download before your next session, run `verity init` again.

### The service is unreachable

Static analysis still runs locally, the hook exits without blocking, the run reports `WARN`, and nothing is uploaded later — the offline record keeps paths and counts, never code. A commit or push is allowed through with the skipped review named.

### The gate reviewed the wrong worktree

Fixed in 0.30.1: the gate resolves the tree from the command itself. If you still see it, update with `npm install -g @codacy/verity-cli@latest`.

## Findings

### It blocked on a file I did not touch

It should not, any more: a finding can only block if the file's bytes were under review in this run, and anything else is downgraded to pre-existing. If you see it, update the CLI and send us the run id.

### The same finding keeps coming back

A finding you settled — fixed, disputed with reasoning, waived — is synced and should stay settled unless it recurs on new evidence. Check `verity status` for what is still open, and if it is a finding you accept, record that: `verity waive <pattern-id> --file <path> --reason "…"`. Repeated advisories on passing turns are matched on meaning and suppressed once answered. See [Findings & verdicts](https://verity.md/docs/findings).

### It keeps failing on something I disagree with

The agent self-heals at most twice per problem, then defers to you — it will not loop. If the finding is wrong, `/verity-feedback` marks it false-positive and it is suppressed going forward. If it is right but accepted, waive it. If the whole class of finding is wrong for this project, narrow the rule's scope in [the Standard](https://verity.md/docs/standard).

### A rule keeps firing on test fixtures, load-test scripts, generated code

Two tools: `.verityignore` for paths that are never worth reviewing, and the pattern's own `rationale` in the Standard to say where it applies. A pattern with no stated scope applies everywhere.

### My `.verityignore` pattern was refused or warned about

A pattern that would exclude the whole repository is refused. A pattern that could hide a secret (`.env`, a broad `config/**`) is allowed but announced, at setup and on any run where it actually excluded a security-sensitive file. And on the turn that edits `.verityignore`, no rules apply at all — that turn reviews everything, by design.

### The finding says “pre-existing”

The file it cites was not in this change, or it sits under an excluded path. It is reported and counted, but it does not block. Fix it whenever you touch that file.

## The dashboard and cost

### Token telemetry is empty

Telemetry only activates on a fresh Claude Code session. If you just enabled it, **restart Claude Code**, then give it a minute of activity. Confirm with `verity telemetry check`. More in [Token telemetry & cost](https://verity.md/docs/cost).

If you turned telemetry on before 0.35.0, Verity wrote it to the project's `.claude/settings.local.json`, and Claude Code 2.1.282 and later ignore it there. Run `verity telemetry install` again: it writes `~/.claude/settings.json` and removes the old keys.

### Claude Code warns that `verity telemetry headers` exited 1

```
otelHeadersHelper failed (OpenTelemetry export headers unavailable): exited 1: Verity telemetry is off here: this directory is not in a Verity project. Nothing is exported from this session.
```

This is expected in a repository that is not a Verity project. Telemetry is set for the whole machine, so Claude Code runs Verity's helper in every session. Outside a Verity project the helper exits 1 on purpose, and Claude Code then exports nothing from that session. Inside a Verity project, the same warning with “has no token on this machine” means you need to sign in: `verity login`. To stop the warning everywhere, turn telemetry off: `verity telemetry uninstall`.

### A session I ran today is not listed

The account-wide list shows the most recent 100 sessions for the status you selected, and the filters narrow those. Switch to **All**, clear the filters, or open the repository itself. A session is **live** only with a heartbeat in the last two hours.

### GitHub sent me to the homepage after installing the app

The homepage forwards you to a page that says the app is installed and what to do next: back in your terminal, press **Enter**; on the web, sign in again to refresh your access.

## Where the evidence is

- `.verity/.logs/stderr.log` — everything Verity printed, plus a block per run naming what it saw. Tokens are scrubbed.
- `.verity/.logs/cli.log` — structured events and HTTP calls.
- `VERITY_TRACE_PHASES=1 verity analyze` — each phase of a review and its duration.
- `verity run <run-id> --json` and the run page in the dashboard — a run in full.
- `verity --verbose <command>` — every request and response.

## Still stuck?

Email [verity@codacy.com](mailto:verity@codacy.com) with the run id and `stderr.log`, or [talk to us on Slack](https://start-chat.com/slack/codacy/C1rsa5). We read every message, and `verity feedback message "…"` reaches the same people.

[Previous Security & privacy](https://verity.md/docs/security)

Source: https://verity.md/docs/troubleshooting
