Troubleshooting
When something isn’t working, start here. This page helps you triage the most common problems, check an integration’s health, and — if you still need us — gather exactly what Serval support needs to help quickly.Common issues
| Issue | Likely cause | Where to go |
|---|---|---|
| A page, or part of a page, is stuck loading | A WAF or proxy is buffering Serval’s streaming responses | Streaming pages behind a WAF or proxy |
| An integration won’t connect | The wrong user connected it, or admin consent is missing | Common permission patterns |
| An integration’s data is missing or out of date | A sync is failing | Reading Sync History |
| A workflow or action fails for one app | A missing permission for that action in the connected app | Where did it break? |
First five minutes
Before escalating, these checks resolve most integration issues or pin down where the problem is:Check Sync History
Open the integration’s Settings → Sync History and look at the most recent
run. A failed run shows an error message — note it.
Re-run the connection check
Run the integration’s health check (named like Test [App] Connection) to
confirm Serval can still authenticate.
Confirm access is still valid
For integrations that act as a specific user (for example, Slack Admin), confirm
that account still has the required access in the connected app. Configuring or
reconnecting an integration requires the Team Manager role.
Integration health and permissions
Reading Sync History
Each integration keeps a Sync History under its settings, showing recent sync runs. A healthy run shows a Success status and a breakdown of items added, updated, and removed. A failed run shows a Failed status with an error message. Serval doesn’t categorize the failure for you, so read the message:- an access or permission error points to the connected account’s permissions;
- a timeout or connection error points to network, DNS, or firewall;
- an authentication error points to expired or revoked credentials — reconnect the integration.
Where did it break?
An integration failure is almost always at one of three points, and identifying which one saves time:- Authentication — Serval can’t sign in to the app. Re-run its health check and look for an auth error.
- Data sync — Serval is connected but can’t read the expected data. Check Sync History.
- Actions — Serval can read data but a specific action fails. This is usually a missing permission for that operation in the connected app.
Common permission patterns
Most integration problems trace back to a handful of setup issues:- The wrong user connected the app. Some integrations act with the connecting user’s permissions. Slack Admin must be connected by an org owner or admin; ServiceNow should use a dedicated service account, not a personal one.
- Missing Microsoft admin consent. Microsoft Graph, Teams, and Exchange Online require an administrator to grant consent; without it, sign-in works but operations return access-denied.
- Google domain-wide delegation or org policy. Google Workspace service-account access needs domain-wide delegation, and an org policy can block it (“Client is unauthorized…” or “Domain restricted sharing policy”).
- Wrong OAuth app type. ServiceNow needs an inbound OAuth app (client-credentials grant); the outbound / third-party options won’t work.
- On-prem networking. LDAP / Active Directory needs firewall egress to the domain controller, DNS resolution, and — for LDAPS — a trusted CA certificate.
Reconnecting and rotating credentials
- Reconnect when an app’s authorization has expired or its scopes changed — re-run its connect/authorization flow.
- Rotate when you’ve changed an API key or secret in the connected system — update it in Serval so the two match.
Getting help from support
What to send us
To skip the back-and-forth, include:- your organization name;
- which integration, and the account or app it’s connected with;
- the error message and timestamp from Sync History;
- your deployment model — Serval Cloud, Hybrid, or self-hosted;
- a support token (below), so we can investigate directly.
Support tokens
A support token lets Serval support securely access your environment for a limited time. From your profile menu, choose Get support and enable support access; the token expires automatically, and every support action is recorded in your Audit Logs. See Support for details.See also
- Network Security and Firewalls — fixes for streaming pages stuck behind a proxy.
- Integrations overview — connecting integrations and reading Sync History.
- Support — support tokens and contacting Serval.