Troubleshooting

Outcome

You can match the exact message or stuck state you are seeing to its cause and the guide that fixes it. Every quoted message below is one the product actually shows.

Who can do it

Anyone. Some recoveries need a specific role — the organization owner for seats and repository access, a site admin for account state — and each entry says so.

Before you begin

• Note the exact message text and where it appeared (banner on the page, or an error response).
• Know your role and scope — most “permission” failures are the access model working as designed. See Roles and permissions.

Steps: general triage

1. Reload the page once — many banners describe an already-resolved transient state.
2. Check your account: profile menu → Settings shows your role, and whether a GitHub token is stored (“Connected.” panel).
3. Check the run itself under Jobs — most build and scan failures carry their reason on the job detail page (see Monitor environments and scan jobs).
4. Match the message in the sections below and follow its recovery link.

Signing in

• You keep landing back on the sign-in page. The session cookie is not being kept — cookies are blocked for the site, or your account cannot hold a session. Allow cookies and retry; if it persists, a site admin should check your account state. → Sign in and set up your account
• “OAuth state mismatch”. The sign-in attempt went stale — the security cookie pairing your browser to the GitHub round-trip expires after 10 minutes, or cookies were blocked mid-flow. Start again from the sign-in page in the same tab. → Sign in and set up your account
• “GitHub OAuth error: …”. GitHub refused the authorization (for example, you pressed Cancel on the consent screen). Retry and approve the prompt. → Sign in and set up your account
• “this account is disabled”. A site admin disabled your account; sign-in is refused even though GitHub authenticated you. Contact your administrator.
• “GitHub OAuth not configured”. The deployment itself is missing its GitHub app configuration — an operator problem, not yours. Contact support.

GitHub tokens and permissions

• Clones fail on a private repository even though you are signed in. Signing in proves identity only; repository access needs a separately stored credential — Connect with GitHub or a fine-grained token saved under Settings → GitHub repository access (the panel shows “Connected.” with the stored scope when present). → Connect GitHub authentication
• “GitHub token auth is only supported for exact HTTPS GitHub repo URLs like https://github.com/owner/repo”. Re-enter the repository as a plain HTTPS github.com URL. → Connect your first repository
• Token works for cloning but the pull request step fails. The PR banner explains: for fine-grained tokens, grant Pull requests: Read and write; classic tokens need the full repo scope. → GitHub authentication and permissions reference
• “you do not have scan access to this repository” / “you do not have review access to this repository” / “you do not have defend access to this repository”. The repository is outside your granted scope or your grants lack that action. The organization owner fixes this. → Assign repository access and roles
• “BYOS launches require a customer account …”. Your role is still waitlist; a site admin must promote you before any cost-incurring work. → Roles and permissions

Connecting a repository

• “repo URL is required” / “repo URL must not contain embedded credentials”. Enter a plain repository URL; put credentials in the token field, never in the URL. → Connect your first repository
• “commit (exact sha or ref) is required — BYOS pins an exact commit, never a moving branch tip”. Pick a commit or ref in the launch form; prpl deliberately refuses a floating default. → Connect your first repository
• “that looks like a CVE id …”. You pasted a CVE number into the repository field; this flow scans your repository. → Connect your first repository

Environment builds

• The Harness build failed or sits in a non-ready state. Open the build under the repository's Build jobs tab (or Jobs) and read the live build log — dependency and setup errors are reported there. → Prepare a repository environment
• The build is paused “waiting for you to review & approve the plan”. Not a failure: interactive builds stop for plan approval. Use Review & approve plan on the build entry — scans cannot run until the plan is approved. → Prepare a repository environment

Scans

• A scan looks stuck or failed. Check its state and logs on the job detail page; long stages are normal, but a failed stage carries its error there. → Monitor environments and scan jobs
• A scheduled scan did not run. The schedule panel shows the last skip reason (for example a missing or expired token, or a scan already in flight). It retries on the next tick once the blocker clears. → Schedule recurring scans

Review and Defend eligibility

• “No defend-ready findings to bundle.” / “Select at least one finding before launching a bundle.” Nothing eligible was selected — findings must be reviewed (acknowledged as true positives) before patch generation. → Acknowledge true positives or reject false positives
• “One or more selected findings are pending review or already defending.” Deselect those rows or finish their review first. → Generate and review patches with Defend
• “Bundle selection must target a single env.” / “Bundle selection must target a single commit/ref.” One bundle produces one diff — select findings from one environment and one commit at a time. → Generate and review patches with Defend

Pull request approval

• The PR did not open after requesting it. Expected — opening a PR is a two-step flow: 1 · Request PR records intent, and a holder of the PR-approval permission must complete 2 · Approve & open PR, which pushes the branch. → Review and approve a Defend pull request
• “PR open failed” banner. The banner includes GitHub's status and hints — most commonly missing token write permission (see the tokens section above) or a branch left behind by an earlier attempt (retry without a branch suffix and the existing branch is reused). → Review and approve a Defend pull request

Invitations and seats

• “Seat limit reached — all licensed seats for this organization are in use. Remove or disable a member to free a seat.” Active members use seats and every live pending invitation reserves one. Free a seat, revoke a pending invitation, or ask a site admin to raise the limit. → Manage members and seats
• “the organization has no available seats” (when accepting). Seats filled between invitation and acceptance. The owner frees a seat, then re-invites. → Invite members with initial repository access
• “invitation is invalid or expired”. Invitation links are single-use and expire after 72 hours; the link also dies if it was revoked or the same address was re-invited (a new invitation rotates the credential). Ask for a fresh invitation — there is no way to revive an old link. → Invite members with initial repository access
• “that email is already an organization member”. No invitation needed — the person can sign in directly. → Sign in and set up your account

Verification

After a recovery, retry the original action: the banner is replaced by its success counterpart (for example “Defend bundle launched.”, “GitHub access token saved.”, “Invitation sent.”), or the job progresses on its detail page.

Still stuck?

If a message is not listed here, capture its exact text and the page it appeared on, and contact your organization owner (access questions) or a site admin (account, seats, platform state).

Next step

Return to Getting started, or continue with Scan and finding lifecycle to see which states are normal at each stage.

Last verified against commit c0bf54d on 2026-07-10 · capture scenario: troubleshooting