PAT and onboarding wizard error codes

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 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 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. 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, 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/<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.

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/<org>."

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). If the original signup email is no longer accessible, open a support request 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 — 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.

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, open a support request — 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 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.