A connected repository does not run reviews
Check installation access, workspace developer entitlement, available credits, organization pause/credit limits, and supported GitHub intake. UI-impact detection can skip a change. A queued commit may be waiting for its predecessor rather than stalled. Open the review’s Run detail for setup or provider failure. Installing the App establishes repository access; it does not seed a database or supply credentials. Operators can runpnpm deployment:check from the Diffraction checkout to inspect
provider prerequisites without printing secrets.
Automatic setup fails
Inspect detected framework, application directory, and commands in Repos → repository → Overview. If several applications are detected, setapp.workingDirectory. For unsupported setup, supply explicit install/build/start
commands and readiness configuration. Use setup and verify commands for synthetic
data prerequisites.
The first existing file wins: diffraction.json, .diffraction/config.json, then
diffraction.yml. An invalid earlier file does not fall back to a later one.
Configuration is optional for supported apps. See configuration.
A rerun confirmation is rejected
Reopen the confirmation if its ten-minute lifetime elapsed or its credit cost changed. For another revision, enter the full SHA and choose Use this commit to obtain a quote for that selection. Check current membership, developer entitlement, and credits. Cancelling a quote does not start a run. A CLI retry must retain both its request key and immutable source; use a new key only when intentionally requesting another paid review.A check is unavailable or has no results
Optional checks require Pro and organization permission. Performance and accessibility default on for repositories without saved settings; existing opt-outs remain in effect. Other checks require explicit repository selection. Saving applies to future runs, not old evidence. Native tests also require explicit catalog selection and synthetic-data confirmation. Comparisons require a configured synthetic state that matches both revisions. Read Coverage and Performance for disabled, partial, unsupported, or unavailable states. Required image-analysis failure makes the review incomplete. A missing measurement or absent finding is not a passing result.A browser or viewport has no recording
Check whether the target completed and capture succeeded. A different browser’s replay or a resized preview cannot fill the gap. Address the failed execution stage before requesting another review.Evidence cannot be opened
Sign in to the correct workspace and inspect the selected target. Evidence can be missing, expired after 30 days, deleted, or inaccessible. Old GitHub summaries can outlive their artifacts. Requesting a new access link cannot restore expired bytes. See retention. For contributor recordings, use the authenticated local dashboard athttp://localhost:3000/reviews. Production cannot serve local filesystem recordings.
CLI installation or login fails
Use the documented curl command and check download errors if installation fails. Confirmdiffraction --version afterwards; a piped shell’s exit status alone is
not proof that the installer downloaded or completed.
WorkOS login uses a browser and http://localhost:53682/callback. If a browser
blocks the callback page, inspect the terminal result; some browser protection
can show an error after the callback reaches the CLI. The CLI must validate the
token audience and scopes before reporting successful login.
Read-only consent cannot perform writes. Reconnect with the needed consent and
check current resource permissions and the organization write ceiling. General
MCP dynamic-client scope setup remains incomplete.
A local-source upload fails
Usereview-local --dry-run --json to inspect files, exclusions, and size limits.
Untracked files need individual --include selections. Unsafe paths, symlinks,
secret-pattern matches, and oversized source fail validation. The server validates
the upload independently; a dry run does not establish remote admission.
The contributor PR harness rejects a checkout
Inspectgit status --short and git rev-parse HEAD in the application repository.
PR mode needs a clean checkout at the exact PR head. Preserve local work before
preparing that revision. Check GitHub CLI and Codex authentication, configuration
detection, and installed Playwright browsers.
A local harness exit code of 1 can mean findings or a failed flow. Inspect the
run and evidence before treating it as a harness failure. CLI hosted commands use
their own exit-code reference.