Troubleshooting Connection & Authentication Issues
Most connection problems are one of a handful of things. Find your symptom below.
Start here
| Symptom | Most likely cause | Fix |
|---|---|---|
| Service shows Not Connected | Connection never completed, or was disconnected | Services → select it → Connect |
| Service shows needs reauthorization | Access token expired, or the grant was revoked at the service | Services → select it → Reauthenticate |
| Status reads Expired — auto-refresh | Nothing. The token lapsed and Gatekeeper is renewing it | No action needed |
| Agent can't see a tool at all | The tool is disabled on that service | Ask an administrator to enable it |
| Action blocked with a reason | A policy decided it | See Troubleshooting Policy Denials |
| Action fails as a permission error | The scope was never granted | Reauthenticate with a broader scope set |
| Action works, but nothing in the audit log | A direct connection is bypassing Gatekeeper | Remove it — see below |
That third row is worth knowing about before it alarms someone. Expired — auto-refresh is a healthy state, not a broken one; the credential lapsed and Gatekeeper is handling renewal on its own.
A service was working and now isn't
Three causes, in rough order of likelihood:
- The access token expired. Many services require periodic reauthentication. Reauthenticate from the Services page.
- Permissions were revoked at the service. If someone revoked the app authorization directly in HubSpot or GitHub, Gatekeeper loses access even though nothing changed on your side. Reconnecting resolves it.
- The connected account lost its own access. If the person who originally connected the service leaves or is removed from that tool, the connection breaks with them.
That last one is worth planning around rather than fixing repeatedly. A connection is only as durable as the account behind it, so connect anything important with an account that won't disappear.
My agent can't do something I expect it to
Four separate things can produce this, and they have different fixes. Work through them in order:
- Is the service connected? Check Services. Connection problems show plainly.
- Is the tool enabled? A disabled tool doesn't appear to your agent at all — this is not a policy denial. See Connection Types.
- Do the scopes cover it? Scopes and policies are separate gates and both must pass. See Understanding Scopes & Permissions.
- Is a policy blocking it? Policy blocks return a denial with a reason, not a connection error.
Everything works, but nothing appears in my audit log
This one matters more than it looks, because nothing appears broken.
If your AI client still has a direct connection to a service alongside its Gatekeeper connection, your agent has two routes to the same tools — and it will use the direct one. That route has no policy checks and writes no audit records.
A successful action with no corresponding audit entry is the tell. Remove the direct connection and try again. See Connecting Your AI Client to Gatekeeper.
Revoking a connection
Grants are listed under Sessions → Downstream, each with a revoke control. Revoking clears the stored credential; the next call requires fresh consent.
Sessions → Gateway is a different thing: it lists AI client sessions and revoking one disconnects that client immediately. Reach for it when the problem is a connected client rather than a service grant.
Still stuck?
Find the failed attempt in Activity. The outcome tells you whether it was a connection problem, a scope problem, or a policy decision — which tells you which fix above applies.
If you still can't place it, contact support with the timestamp of the attempt.