Troubleshooting

Nothing appears on the pull request

Is the repository covered by the App? Check Repos in the web app, or the installation on GitHub. Verity gets no events for repositories outside the installation.
Is the check waiting? Waiting for session upload means a linked session is still uploading. The check updates once it finishes, or at the time the check names, whichever comes first.

"No rules checked"

There's no .verity/rules.yml on the base branch, or Verity can't read it.

Run npx @veritypr/cli capture init to write a starter file, and merge it into the base branch. Rules are read from the base branch, so a file added in a pull request applies from the next one.
If the file is there, the App may not have the Single file permission yet. An org owner approves it on GitHub; the Setup page says when it's missing. See Install the GitHub App.

A rule fired and it shouldn't have

Rules fail closed. An unsure answer, or no answer, fires the rule. An unsure answer alone makes a fail rule a warning. If a question rule fires often on good changes, make the question more specific, or narrow its files.
A rule that needs the session fired on a pull request without one. Set no_session: pass on the rule if that's fine for it.
The change is fine this time. A reviewer who isn't the author adds the label verity-override:<rule id>. See Overrides.

The label counts only when a GitHub user who isn't the pull request's author adds it. The comment says "not accepted (author or bot)" when it came from the author or a bot. Ask another reviewer to add it.

Sessions aren't uploading

Check that verity is on your PATH (npm install -g @veritypr/cli). The hooks do nothing without it.
Look in ~/.local/state/verity/capture.log for errors.
If the log says to run verity capture login, your sign-in expired. Sign in again: sessions waiting on the machine upload at the next hook.
Check that the repository is in the App's installation. Uploads to a repository it doesn't cover are refused, and the log says so.
Check that .claude/settings.json with Verity's hooks is committed on the branch you're working on.
If the log says a session is too large to upload, it's over 64 MB. Verity reviews that session's pull requests without it; see Sessions too large.

No session linked

The check title ends in "no session linked", and there is no brief. Rules are still checked. Sessions are linked by the Agent-Session trailer that capture adds to commits; when it's missing, Verity matches sessions by branch and time.

If the repository has rules, the Verity comment on the pull request lists them as usual and says that no session was linked. Without rules, Verity comments only when the commits say an agent wrote them. The author installs the CLI and signs in (see Capture sessions), and the next push has a brief.

Linked sessions never arrived

The check is titled "Linked sessions never arrived", or the Verity comment says the commits name agent sessions that never reached Verity. Capture added Agent-Session trailers to the commits, so it ran, but it didn't upload the sessions. On the machine that made the commits:

Run verity capture login. Each Verity server has its own sign-in, and the verity from npm uploads to https://veritypr.dev only, so a sign-in to another server doesn't count.
Look in ~/.local/state/verity/capture.log for why uploads failed, and see Sessions aren't uploading.

Sessions waiting on the machine upload at the next hook, and the pull request is analysed again when they arrive.

Limited briefs

Reason	What it means	What to do
No agent session linked	No session was uploaded for the pull request.	Set up capture; see above.
Mostly human or shell edits	Under half of the diff comes from edits in the session.	Nothing to fix: most of this change wasn't made through the agent's file tools. Review it as usual.
No steps of the session fall in this PR's slice	The linked session was split across pull requests, and none of it belongs to this one.	Check that the commits' trailers point at the right session.
The PR diff has no changes to attribute	The diff is empty.	Nothing to fix.
Unknown transcript format	Claude Code changed its transcript format.	Nothing to do on your side: Verity needs an update.
Session storage unavailable	Your organization keeps transcripts in its own bucket, and Verity couldn't read it.	See below.
Sessions too large	The sessions linked to the pull request are more than Verity reviews together.	See below.
Plan limit reached	Your organization is on the Free plan and has used this month's 100 pull requests.	Rules are still checked. The brief returns on the first of next month. See Plans and limits.

Session storage unavailable

Session storage unavailable means your organization keeps session transcripts in its own bucket, and Verity couldn't reach it: the access key was revoked or lost its permissions, or the bucket was deleted or renamed. Org rules still run, and a rule that needs the session is reported as a warning. An org owner sees the error in Settings; see When the bucket can't be reached.

Sessions too large

Verity reviews a session of up to 64 MB, and up to 128 MB of sessions on one pull request. Capture doesn't upload a session over 64 MB, and says so once in ~/.local/state/verity/capture.log. When a pull request's linked sessions together are over 128 MB, its check is titled Sessions too large to review:

org rules are still checked;
a rule that needs the session is reported as a warning, so it doesn't block the merge;
the report says why.

Sessions this large are usually long ones that ran across many tasks. Starting a new Claude Code session for each pull request keeps them small.

Session expired

Session expired means the linked sessions' transcripts passed the organization's transcript retention, so a new push can't be briefed again. The last report stays available until it expires. Org owners can change transcript retention in Settings.