Background
Pylon #802 — A developer building a Jira connector in AgentKit repeatedly hit this error when completing the connection flow:
"Your verification session has expired or is no longer valid. Please close this window and restart the connection flow."
Error URL:
/ui-handlers/connect/callback/error?error=failed_to_exchange_token&error_description=error+%3D+server_error%2C+description+%3D+Error+executing+post+auth+hooks
The root cause was a session verification bug in the platform that was patched and rolled out same-day. The developer confirmed it was fixed after the rollout.
Problem
There is no troubleshooting documentation for connector setup errors in AgentKit. When a developer hits failed_to_exchange_token or Error executing post auth hooks, they have no self-serve path — they have to open a support ticket.
Proposed work
Add a troubleshooting section to the AgentKit connection docs covering:
failed_to_exchange_token: What it means (OAuth token exchange failed after the user completed the consent screen), common causes (session expired, post-auth hook error, network issue between provider and Scalekit), and what to try (restart the connection flow; if it persists, check the Scalekit status page or open a support ticket)redirect_uri_mismatch: Already partially covered; consolidate here- Session expired / invalid: Explain when this happens (long delay between opening the OAuth flow and completing it) and how to resolve it (restart the flow)
Suggested location: a new ## Troubleshooting section at the bottom of src/content/docs/agentkit/connections.mdx, or a standalone src/content/docs/agentkit/troubleshooting.mdx.
Additional context
- The
Error executing post auth hooks description suggests a server-side hook failure. Documenting this error code specifically would help developers distinguish a transient platform issue from a misconfiguration they can fix themselves.
- Consider linking to a status page from the troubleshooting section so developers can check for ongoing incidents before filing a ticket.
Background
Pylon #802 — A developer building a Jira connector in AgentKit repeatedly hit this error when completing the connection flow:
Error URL:
The root cause was a session verification bug in the platform that was patched and rolled out same-day. The developer confirmed it was fixed after the rollout.
Problem
There is no troubleshooting documentation for connector setup errors in AgentKit. When a developer hits
failed_to_exchange_tokenorError executing post auth hooks, they have no self-serve path — they have to open a support ticket.Proposed work
Add a troubleshooting section to the AgentKit connection docs covering:
failed_to_exchange_token: What it means (OAuth token exchange failed after the user completed the consent screen), common causes (session expired, post-auth hook error, network issue between provider and Scalekit), and what to try (restart the connection flow; if it persists, check the Scalekit status page or open a support ticket)redirect_uri_mismatch: Already partially covered; consolidate hereSuggested location: a new
## Troubleshootingsection at the bottom ofsrc/content/docs/agentkit/connections.mdx, or a standalonesrc/content/docs/agentkit/troubleshooting.mdx.Additional context
Error executing post auth hooksdescription suggests a server-side hook failure. Documenting this error code specifically would help developers distinguish a transient platform issue from a misconfiguration they can fix themselves.