Connecting Azure DevOps in Step 2 of the onboarding wizard happens in two stages: first it validates your personal access token (PAT) and first pull request URL, then — once validation passes — it provisions a tenant for your organization. An error at either stage surfaces a specific code and message that pinpoints what to fix. This page is the reference for every PAT- and PR-URL-related code, what triggers it, and how to resolve it. (Codes specific to the [service principal](../connecting-ado/service-principal-setup.md) auth flow — for example, an organization that isn't backed by Microsoft Entra — are covered on that page instead.) ## Where these errors appear The wizard renders the error in a single alert banner near the **Connect & Continue** button, below the connection form. The banner shows a one-sentence human-readable 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](../getting-started/quickstart.md) for the full happy-path flow. ## Symptom During Step 2 of the onboarding wizard ("Connect Azure DevOps"), an error banner appears near the **Connect & Continue** button after you submit your PAT and pull request URL. The banner shows a one-sentence human-readable message; the underlying machine-readable error code is one of the entries in the reference below. Match the message you see against each entry's **What you see** line to find the right 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), Code (Status), and Pull Request Threads (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](../connecting-ado/creating-a-pat.md#required-scopes). Paste the new PAT into the wizard. See [Creating a Personal Access Token](../connecting-ado/creating-a-pat.md) 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, or pasting a URL from a fork or downstream tool. (A well-formed legacy `https://{org}.visualstudio.com/{project}/_git/{repo}/pullrequest/{id}` URL is supported and won't trigger this error.) **Fix:** Open the PR in Azure DevOps and copy the URL from the browser address bar exactly. It should end in `/pullrequest/` 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 — the project, repo, or PR ID in the URL does not exist. A PAT missing **Code (Read)** access is caught earlier, as `pat_missing_scope`, rather than reaching this 404. **Fix:** Open the PR in your browser to confirm it exists and is in the expected project, repo, and PR number. PATs inherit the access of the user who created them — a PAT from a guest account may not see internal repos, which can also produce this 404. ### `org_not_found` **What you see:** "We couldn't find an Azure DevOps organization with that name. Double-check it — it should match the org segment of `https://dev.azure.com/`." **Trigger:** You chose **Skip for now** and typed an organization name (rather than a PR URL), and Azure DevOps has no organization by that name. Almost always a typo or the wrong slug. (If you paste a PR URL instead, a bad org in that URL surfaces as `pr_not_found` above, since org, project, repo, and PR can't be distinguished from a 404 that early.) **Fix:** Correct the organization name in the **Organization Name or URL** field and click **Connect & Continue** again. The wizard also shows a persistent "Fix organization name →" banner above the steps until the name resolves — its link jumps you straight back to the field. ### `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](../team/inviting-members.md)). If the original signup email is no longer accessible, [open a support request](../trust/support-and-contact.md) 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 while securely storing 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, open a [support request](../trust/support-and-contact.md) — 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; open a [support request](../trust/support-and-contact.md). ### `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](https://status.dev.azure.com/) for incidents. If ADO is healthy, retry in a minute or two. If retries keep failing for more than 15 minutes, open a [support request](../trust/support-and-contact.md) — that combination usually means the problem is on our side. ## How to prevent these errors - **Create the PAT with all three scopes the first time.** Use the [Required PAT scopes](../connecting-ado/creating-a-pat.md#required-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.