PAT and onboarding wizard error codes

The onboarding wizard validates your personal access token (PAT) and first pull request URL before it provisions anything. If validation fails, it surfaces a specific error code and message that pinpoints what to fix. This page is the reference for every code, what triggers it, and how to resolve it.

Where these errors appear

The wizard renders the error in an alert banner under the field that failed. The banner shows a one-sentence human message; the underlying error code is included in support diagnostics. The codes below match the verbatim strings from the wizard's error map.

If you have not started the wizard yet, see Quickstart for the full happy-path flow.

Symptom

During Step 2 of the onboarding wizard ("Connect Azure DevOps"), an error banner appears under the Personal access token field or the First pull request URL field. The banner shows a one-sentence human-readable message; the underlying machine-readable error code is one of the entries in the reference below. Each error pinpoints exactly which input failed validation, so use the code (not the prose) to find the matching fix.

Error code reference

pat_missing_scope

What you see: "The PAT is missing one or more required scopes. Please create a new PAT with Code (Read & Status), Pull Request Threads (Read & Write), and Service Hooks (Read & Write)."

Trigger: The PAT you pasted does not include every scope ADO Pilot requires. Azure DevOps does not let us add scopes to an existing PAT — you have to create a fresh one with all the required scopes checked.

Fix: Go to User settings → Personal access tokens in Azure DevOps and create a new PAT with the scopes listed in Required PAT scopes. Paste the new PAT into the wizard. See Creating a Personal Access Token for screenshots.

pat_invalid_or_expired

What you see: "The PAT appears to be invalid or expired. Please create a new one and try again."

Trigger: Azure DevOps rejected the PAT outright — it is either malformed, revoked, or past its expiry date.

Fix: Create a new PAT in Azure DevOps and paste it into the wizard. Double-check that you copied the entire token (PATs are long; truncation is a common cause).

invalid_pr_url

What you see: "That PR URL could not be parsed. Expected format: https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id}"

Trigger: The URL you pasted does not match the format above. Common mistakes: pasting the Files or Commits sub-URL instead of the PR root, pasting a visualstudio.com legacy URL, or pasting a URL from a fork or downstream tool.

Fix: Open the PR in Azure DevOps and copy the URL from the browser address bar exactly. It should end in /pullrequest/<number> with no trailing path or query string.

pr_not_found

What you see: "We couldn't find that pull request. Double-check the URL and make sure the PAT has access to the project."

Trigger: The URL is well-formed but the API call to fetch the PR returned 404. Either the PR ID does not exist in that repo, or your PAT does not have Code (Read) access to the project containing the repo.

Fix: Open the PR in your browser to confirm it exists and is in the expected project. If it does, verify that the PAT was created by an account that can see the repo. PATs inherit the access of the user who created them — a PAT from a guest account may not see internal repos.

pr_closed

What you see: "That pull request is already closed. Please paste a link to an open pull request."

Trigger: The wizard requires an active PR for the first review so you can immediately see the output. The URL you provided points to a PR that is completed or abandoned.

Fix: Pick an open PR in the same repo, or open a small new PR specifically for this onboarding step. Once provisioning completes, ADO Pilot will pick up new PRs automatically — the first PR is just a smoke test.

trial_already_exists

What you see: "An active trial already exists for this Azure DevOps organization. Contact your admin or sign in with the existing account."

Trigger: A teammate already started an ADO Pilot trial for the same Azure DevOps organization. Trials are one-per-org to prevent accidental double signup.

Fix: Find the teammate who started the trial and have them invite you (see Inviting team members). If the original signup email is no longer accessible, contact support to transfer ownership.

encryption_failed

What you see: "We couldn't securely store your PAT. Please try again in a moment."

Trigger: A backend error in the envelope-encryption pipeline that wraps your PAT before it lands in our database. Almost always transient.

Fix: Wait 30 seconds and retry the wizard step. If you see this error twice in a row, contact support — repeated encryption_failed indicates an infrastructure issue on our side, not anything you can resolve.

cosmos_write_failed

What you see: "We couldn't save your configuration. Please try again in a moment."

Trigger: The wizard validated your inputs but failed to persist them to the configuration store. Transient backend issue.

Fix: Retry the wizard step. If it fails repeatedly, refresh the page and start the step again. Persistent cosmos_write_failed is on us; contact support.

ado_unreachable

What you see: "We couldn't reach Azure DevOps. Please check your internet connection and try again."

Trigger: The backend could not connect to the Azure DevOps REST API to validate your PAT or fetch the PR. Either ADO is having an incident or there is a network problem between our backend and Azure DevOps.

Fix: Check the Azure DevOps service status page for incidents. If ADO is healthy, retry in a minute or two. If retries keep failing for more than 15 minutes, contact support — that combination usually means the problem is on our side.

How to prevent these errors

• Create the PAT with all four scopes the first time. Use the Required PAT scopes reference and check every box before generating.
• Paste the URL from the browser address bar. Copying from a chat link, email forward, or paste-buffer manager is where most invalid_pr_url errors come from.
• Pick a stable PR for first-run validation. A PR that is actively being merged may close mid-wizard and trip pr_closed.
• Treat your PAT like a password. If it leaks, anyone can act as you against your ADO org. Revoke and rotate any PAT that you have shared, pasted into the wrong tool, or committed by mistake.