Repository navigation
Web Portal Troubleshooting
Sam Betts edited this page Nov 12, 2026
·
3 revisions
Troubleshooting → Web Portal Troubleshooting
This page is for portal administrators, and for anyone who sees an error message, a - instead of a number, or an empty report in the web portal. It lists the messages the portal shows, what each means and what to do, then the symptoms of the optional Copilot, billing and catalogue features. It describes Stable 1856 and later. On an older build, check Known issues → Fixed issues first: upgrading may be the fix.
Elsewhere:
- A 403, a missing menu item or a role problem: Portal permission verification.
-
AADSTS65001when connecting to Microsoft Teams: Known issues → AADSTS65001. - A person counted as licensed or unlicensed when they shouldn't be: User licence diagnostics.
- Agent and Copilot Studio costs: Agent costs verification and troubleshooting.
| Where | What you see | What it means | What to do |
|---|---|---|---|
| Insights → Overview | A tile shows - instead of a number |
That figure couldn't be counted just now. Most counts come from SQL's own row-count metadata, the same source as Service health → Data overview, and the whole set gives up after 30 seconds rather than holding up the page. | Reload a minute later. If it persists, check Service health and look in the web app's Application Insights for traces starting Home page figure. |
| Administration → Teams permissions | Couldn't reach Microsoft Entra ID to refresh your Teams connection. Try again in a few minutes. and a Try again button | The web app couldn't refresh your connection because Entra ID was unreachable, timed out, throttled the request or failed. Connecting again wouldn't help, because it ends at the same Entra ID endpoint. | Wait, then select Try again. If it persists, check the web app's outbound access to Microsoft Entra ID. |
| Administration → User scope, starting a purge | More people are outside the scope now than the number you confirmed, so the purge did not start and nothing was removed. Check the new number, then tick the box again to confirm it. | The number outside the scope grew between showing it to you and starting the purge (HTTP 409). |
Check the new number on the page, then confirm again. See Purging people outside the scope. |
| Administration → User scope, starting a purge | UserGroupsFilter has changed since this page was loaded, so the purge did not start and nothing was removed. Check the filter and the new numbers, then confirm again. | The filter changed after the page loaded (HTTP 409). |
Check the filter and the new numbers, then confirm again. |
| Administration → Prompt categories, saving or resetting | The prompt categorisation settings were changed after this page loaded them, so nothing was saved. Reload to see the current settings, then make your changes again. and a Reload button | Another administrator saved or reset the settings in the meantime (HTTP 409). |
Select Reload, then make your changes again. |
| Administration → Service health | Couldn't load import liveness: Timed out after 40 seconds. (or exceptions, or component health) | Application Insights or Service Bus didn't answer within 40 seconds. The section is shown as unavailable instead of holding up the page; it's tried again 20 seconds later. Component health that timed out counts as a failed check, never as all checks passing. | Reload after a short wait. If it persists, check Application Insights and Service Bus. |
| Administration → User import | Couldn't load the user import checkpoint (503). or Couldn't clear the user import checkpoint (503). | If the web app's log says User import checkpoint - couldn't read the configured user organisation types (...), so the checkpoint key cannot be worked out, the database couldn't be read, so the page couldn't tell which row holds the checkpoint. Nothing was cleared.
|
Try again once the database answers. |
| Insights → Teams Explorer, exporting | Couldn't export dormant (503). (or people, teams, channels, adoption) | The query behind the file failed. | Try again later. If it persists, check the database's load. |
| Any page, from a browser other than one on the web server itself | A generic error page with no exception details | The website's release configuration sets customErrors mode="RemoteOnly", and its API returns no exception details to remote callers. |
Look the error up in the web app's Application Insights (the exceptions table), where it is still recorded. |
| A script, or the portal behind a reverse proxy or Application Gateway, changing something through the portal's API | A bare 403, and the change isn't made |
Since Stable 1859 (PR #825), every API call that can change something (any method but GET, HEAD, OPTIONS and TRACE) must carry X-Requested-With: XMLHttpRequest, and come from the portal's own origin when the browser sends Sec-Fetch-Site. This is the portal's protection against cross-site request forgery; the portal itself always sends the header. |
Make the script send X-Requested-With: XMLHttpRequest, and make sure the proxy doesn't strip it. See Security model → Who can use the web portal. |
A bookmark, favourite or documentation link to /Account/SignOut or /Account/ConnectTeams
|
404 |
Since Stable build 1860 (PR #865), signing out and connecting to Microsoft Teams accept only a POST from the portal's own pages, so a GET link no longer works. |
Use the Sign out button in the portal's header, or Connect to Microsoft Teams on Administration → Teams permissions, and replace the bookmark or link with an instruction to use them. See Security model → Who can use the web portal. |
| Copilot Adoption (with its CSVs and workbook), Web activity, Teams Explorer, Reports or Office apps | A section says why its query failed, with an error reference, such as the query timed out (error reference …) | Since Stable 1859 (PR #825), readers see a reason and a reference instead of SQL Server's error text, which can name servers or quote data values. | Search the web app's Application Insights traces for the reference: the warning that carries it, errorReference=<reference>, gives the reason, the SQL error number and the exception types. |
Symptoms of the optional Copilot, billing, licence-activity and catalogue features, with the first thing to check for each.
| Symptom | Check/remedy |
|---|---|
Copilot Adoption returns copilotAdoptionSettingsUnavailable / 503 |
Check Storage, Table DNS/network and runtime permissions. The ten-second storage deadline includes opening/reads/writes; unreadable settings refuse even a cached report. Do not bypass it with different/default scores |
| Score-settings save times out | Restore Table access, then read current settings/history before retrying; the write may have completed. Reload the current version, not the old form |
| Admin cannot switch a global filter off | Both Administration and See PII are now required; an old bypass cookie does not grant either |
| Entire licence workload is Unknown | Use coverage diagnostics, not a zero-usage interpretation |
| Billing says connection required/reconnect needed | Follow delegated connection setup, exact callback/consent/account/Table checks |
| Billing user rows were read but the user phase failed | Check its SQL write error. Rows read are not successful persistence; a completed empty phase can legitimately succeed. A later agent/resource failure does not reverse a completed user phase |
| Prompt-category report is empty | Verify history import, durable opt-in/backend, immutable selected version, caps/failures and ten distinct people per group. Audit is not the text source; old discarded prompts are not automatically recategorised |
| Prompt insights is missing when only the interaction-history import is on | Insights → Copilot → Prompt insights is shown when either the Copilot audit import or the interaction-history import is on. Check that the interaction-history import is enabled and that the portal is the same build as the importer. Seeing the page doesn't grant categorisation consent |
| Leadership is pending/stale/suppressed | Keep the importer running, check cached status, current direct membership and the small cohort/complement floor; See PII does not waive suppression |
| Catalog reports failed / usage not reported | Check Agent 365 licence, CopilotPackages.Read.All consent/global cloud and last completed snapshot; missing metrics are not zero/billing |
Return to Troubleshooting · All topics in this guide
Previous: Web Tracking Troubleshooting · Next: Storage Firewall Troubleshooting
- Copilot analytics overview
- Copilot Adoption user guide
- Copilot Adoption setup (admins)
- Work Trend Index
- Copilot investment
- Copilot spend
- Agent costs
- Prompt categories
- Copilot credit history (preview)
- Agent 365 package catalog
- The Copilot data in depth
- Prerequisites
- App registrations setup
- Install with the installer
- Verify the deployment
- Security & permissions model
- Private endpoints (optional)
- Certificate authentication (optional)
- Manual installation
- Activity & usage analytics (Power BI)
- SharePoint page tracking