> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diffraction.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Check configuration, revision identity, coverage, and artifact access.

## A connected repository does not run reviews

Installing the GitHub App establishes access. Review execution also needs the
operator's identity, storage, sandbox, and model configuration. Check the
deployment's reported state; operators can run `pnpm deployment:check` from the
Diffraction checkout to inspect missing configuration without printing secrets.

Check that the event is a supported pull request action and that UI-impact
detection selected the change for review. The
[GitHub guide](/docs/site/github) lists supported intake actions.

## The local PR command rejects the checkout

From the application repository, inspect `git status --short` and
`git rev-parse HEAD`. PR mode requires a clean checkout matching the exact PR head
SHA. Preserve your work before preparing that revision; do not discard changes
just to satisfy the check.

Confirm GitHub CLI and Codex authentication, then verify `diffraction.yml` exists
at the application repository root. Adapt the example commands to that project's
package manager and scripts.

## The command exits with code 1

An exit code of `1` can indicate findings or a failed flow. Open the local review
and read its coverage, failed step, and captured evidence. If no run appears,
inspect the command output for a setup or configuration error.

## A browser or viewport has no recording

Check whether that target completed and whether artifact capture succeeded.
Another browser's replay cannot fill the gap. Missing targets leave coverage
incomplete; rerun after addressing the reported failure.

## A recording cannot be opened

For hosted evidence, sign in to the workspace that owns the review and check
whether the artifact has expired or been deleted. For local evidence, use the
local dashboard at `http://localhost:3000/reviews` with the configured staging
identity. Production cannot serve a recording from your development machine.

## Local sign-in returns to the wrong address

Use port 3000 for the Diffraction application. The registered WorkOS callback and
versioned auth configuration must agree. The documentation preview uses port
3001 specifically to avoid changing the application callback.

## Information to include when investigating

Keep the review ID, commit SHA, browser, viewport, failed step, and relevant error
message together. Link to existing evidence when access permits. Never paste
provider credentials or private keys into reports.