Skip to main content

Troubleshooting

Common issues and resolution steps for The One Portal.

1. Login fails with "Invalid credentials"​

Symptoms: Entering correct email and password returns an error.

Causes and fixes:

  • Wrong password — Use the "Forgot password?" link on the login page to reset.
  • Account not active — Ask your MSP admin to check the user account status in Admin → Clients → [Company] → Users. Status must be active.
  • Wrong email — Confirm the exact email address used when the account was created. Email matching is case-insensitive but must be exact.
  • Account is invited status — The account was created but the invite was never accepted. Ask your MSP to resend the invite email.

Symptoms: Clicking the portal link sent from Hub/PSA results in an error page.

Causes and fixes:

  • Link is more than 70 seconds old — Hub SSO tokens expire after 70 seconds. Request a fresh link.
  • Link already used — Each link can only be used once (JTI replay prevention). Request a new link.
  • PORTAL_CLIENT_SSO_SECRET mismatch — The secret on the Hub API and Portal API do not match. MSP admin must verify both values are identical.
  • PORTAL_CLIENT_SSO_SECRET not set — The error "Client SSO not configured" means the env var is missing on the Portal API Function App.

3. Portal loads but shows no content (blank or spinner that never resolves)​

Symptoms: After login, pages appear blank or the loading spinner spins indefinitely.

Causes and fixes:

  • Wrong tenant slug — Verify the ?tenant= parameter in the URL. The slug must exactly match what was configured in the Portal Admin.
  • Branding fetch fails — If the GET /portal/branding?tenant=SLUG call fails (wrong slug), the portal may not initialize correctly. Check the browser console for API errors.
  • Portal API is down — Check that theoneportal-api.azurewebsites.net is running. Look for Function App errors in the Azure portal.
  • CORS error — Check the browser console for CORS errors. Ensure the portal's frontend domain is in the @theonefamily/cors allowed origins list.

4. Tickets do not appear in The One PSA​

Symptoms: Client submits a ticket in the Portal, but technicians cannot find it in PSA.

Causes and fixes:

  • PSA integration not configured — In PSA Settings → Integrations → Portal, verify the integration is enabled and the key matches.
  • PSA_SERVICE_KEY not set — Check the Portal background Function App's application settings.
  • Sync timer not running — The ticket-sync timer runs every 5 minutes (0 */5 * * * *). Check the timer function is deployed and healthy in the Azure portal.
  • Sync error in logs — Check Application Insights or Function App logs for errors in ticket-sync.

Wait up to 5 minutes for the next sync cycle before diagnosing further.

5. Documents tab shows "No documents awaiting your signature" but you expect one​

Symptoms: A policy was issued but does not appear in the "Needs Your Signature" tab.

Causes and fixes:

  • Policy not pushed to Portal — The Legal API integration may not be configured. The PORTAL_INTEGRATION_KEY on the Legal API must be set and the push endpoint must be reachable.
  • Issued to wrong client — The policy may have been issued to a different company. Check in Admin → Documents to see what is assigned to the client.
  • Policy is in draft status — Draft policies are not visible to clients. The MSP must publish/issue the policy.
  • Client user ID mismatch — If the user was auto-provisioned via SSO, their ID may not match what was used when the policy was issued.

6. Mission pages show no data (Giving, Events, Groups, etc.)​

Symptoms: All Mission module pages are empty or show an error.

Causes and fixes:

  • MISSION_API_URL not set — The Portal API's mission-proxy function has no URL to proxy to. Set this on the Portal API Function App.
  • MISSION_SERVICE_KEY not set — The proxy cannot authenticate to Mission. Set the key.
  • Mission API is down — Check The One Mission API health at its function app URL.
  • Wrong domain — Mission mode requires accessing the portal via portal.theonemission.com or portal.theonemission.app. Accessing via the MSP portal domain will not show Mission content.

7. Invoices are not appearing​

Symptoms: Invoice page is empty for a client who has been billed.

Causes and fixes:

  • Invoice sync hasn't run yet — The sync timer runs every 6 hours. Wait for the next cycle.
  • BOOKS_SERVICE_KEY not set — Check the Portal background Function App application settings.
  • Invoice is in draft status in Books — Draft invoices are synced but have a "draft" badge. Ensure you're not filtering them out.
  • Wrong client ID mapping — If the Books client ID doesn't match the Portal client ID, invoices won't be attributed. Check the client mapping in Books → Settings → Portal Integration.

8. Emails (invites, password resets) are not being received​

Symptoms: Client reports no invite or reset email arrived.

Causes and fixes:

  • Check spam/junk folder — The sender domain may be flagged by the client's mail filter.
  • SES_FROM_ADDRESS not verified in AWS SES — Unverified sender addresses will silently fail. Verify the sender in the AWS SES console.
  • SES sandbox mode — AWS SES accounts start in sandbox mode, which only allows sending to verified recipient addresses. Request production access.
  • Email in wrong status — The client user's email address may have a typo. Check the user record in Admin → Clients.

9. Branding / colors not appearing correctly​

Symptoms: Portal shows default violet colors instead of MSP brand colors.

Causes and fixes:

  • Branding not configured — Go to Admin → Branding and set the primary and accent colors.
  • ?tenant= missing from URL — Without the tenant param, the portal uses default branding. Ensure the URL or custom domain is correctly configured.
  • Browser cache — Branding is fetched on each session start. Hard refresh (Ctrl+Shift+R) to clear cached assets.
  • Tenant slug mismatch — The branding lookup uses the tenant slug. Verify it matches exactly.

10. Document signing fails at the "Sign Document" step​

Symptoms: Clicking "Sign Document" shows an error message.

Causes and fixes:

  • Session expired — If the user spent too long reading the document, their session may have expired. Have them log in again and re-sign.
  • Policy already signed — If the same user tries to sign twice, the API will reject the duplicate. Check the Signed Documents tab.
  • Network error — Check the browser console for a failed POST /portal/signing/acknowledge request. Retry after checking connectivity.
  • Policy ID invalid — If the URL was manually altered (e.g., the policyId in /portal/documents/{policyId}/sign), the policy lookup will fail. Navigate back to Documents and click the correct link.

When to Contact Support​

Self-resolve the issues above first. Contact support (via The One Stack Hub or ticket) if:

  • Portal API is returning 500 errors consistently
  • Cosmos DB connectivity is failing
  • An Azure Function App is showing "0 functions deployed"
  • CORS errors persist after verifying domain configuration
  • SSO secret rotation is needed
ℹ️

For development and deployment issues, refer to the BaseKnowledge TROUBLESHOOTING.md.