Failed to start server

website/docs/docs/platform/git/authenticate-azure.md

@@ -11,7 +11,7 @@ availability:
 ---
 
 
-If you use the <Constant name="studio_ide" /> or <Constant name="dbt" /> CLI to collaborate on your team's Azure DevOps dbt repo, you need to [link your <Constant name="dbt" /> profile to Azure DevOps](#link-your-dbt-cloud-profile-to-azure-devops), which provides an extra layer of authentication.
+If you use the <Constant name="studio_ide" /> or <Constant name="dbt" /> CLI to collaborate on your team's Azure DevOps dbt repo, you need to [link your <Constant name="dbt" /> profile to Azure DevOps](#link-your-dbt-profile-to-azure-devops), which provides an extra layer of authentication.
 
 ## Link your dbt profile to Azure DevOps
 
@@ -28,6 +28,30 @@ Connect your <Constant name="dbt" /> profile to Azure DevOps using OAuth:
 
 You will be directed back to <Constant name="dbt" />, and your profile should be linked. You are now ready to develop in <Constant name="dbt" />!
 
+## Troubleshooting
+
+The following section provides troubleshooting steps for common issues when authenticating with Azure DevOps.
+
+<Expandable alt_header="Missing Azure user error when starting Studio">
+
+If the <Constant name="studio_ide" /> fails to start and displays the following error, your personal Azure DevOps account isn't linked to <Constant name="dbt" />:
+
+`Missing Azure user; link your Azure DevOps account in your personal profile`
+
+To resolve it, [link your dbt profile to Azure DevOps](#link-your-dbt-profile-to-azure-devops).
+
+</Expandable>
+
+<Expandable alt_header="Azure Service User not found error when starting Studio">
+
+If the <Constant name="studio_ide" /> fails to start and displays the following error, the account-level service user isn't connected:
+
+`Failed to start server. The project is not fully set up: Azure Service User not found`
+
+This applies to accounts that use the legacy service user authentication. An account admin needs to reconnect the service user, which is also required when an account has had no scheduled, API, or CI runs for over 90 days. Refer to [Connect a service user](/docs/platform/git/setup-service-user#connect-a-service-user) for more details.
+
+</Expandable>
+
 ## FAQs
 
 <FAQ path="Git/gitignore"/>

website/docs/docs/platform/git/setup-azure-service-user.md

@@ -140,6 +140,13 @@ A service user is a pseudo user set up in the same way an admin would set up a r
 
 :::
 
+If the <Constant name="studio_ide" /> fails to start, the cause depends on which connection is missing:
+
+- `Azure Service User not found`: the account-level service user isn't connected. Reconnect it using the OAuth flow described above.
+- `Missing Azure user`: the developer's own Azure DevOps account isn't linked to <Constant name="dbt" />.
+
+Refer to the [troubleshooting steps in Authenticate with Azure DevOps](/docs/platform/git/authenticate-azure#troubleshooting) to resolve either error.
+
 ### Service users permissions
 
 A service user account must have the following Azure DevOps permissions for all Azure DevOps projects and repos you want accessible in <Constant name="dbt" />. Read more about how <Constant name="dbt" /> uses each permission in the following paragraphs.