Skip to main content

​
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

​
First five minutes

Before escalating, these checks resolve most integration issues or pin down where the problem is:
1

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.
2

Re-run the connection check

Run the integration’s health check (named like Test [App] Connection) to confirm Serval can still authenticate.
3

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.
4

Capture the details

Note the exact error message and the timestamp — you’ll need these if you contact support.

​
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:
  1. Authentication — Serval can’t sign in to the app. Re-run its health check and look for an auth error.
  2. Data sync — Serval is connected but can’t read the expected data. Check Sync History.
  3. 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.
Both require the Team Manager role.

​
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