# Troubleshooting and Support Readiness From [Troubleshooting and Support](https://learn.descope.io/c/troubleshooting) — Find out what actually happened, then hand somebody else enough to act on it. Take this course interactively at https://learn.descope.io/c/troubleshooting/troubleshooting --- Audit logs are Descope's system of record for who did what, and when. They cover individual end-user activity — logins, profile changes — and administrative activity such as role changes, SSO configuration, and tenant management, which makes them the first stop for debugging and compliance questions alike. Events come in two scopes. Project-level events record activity inside a single project: end-user logins, user and tenant changes, flow updates, role and permission edits. Company-level events record actions spanning your whole Descope company — creating or deleting projects, managing management keys, changing company settings — and are tagged `Level=Company` inside the same audit table. You can query all of it three ways: the Audits page in the Console, the Management SDKs, or the Search Audit API. ## Fields every event carries - Actor ID — who performed the action: a Descoper's user ID, or the management key ID if the call came from the API or SDK. - User ID — the user the action was performed on. - Action and Occurred — what happened, and when. - Device, Method, Remote Address, Country — the origin of the request. - Data — the full request payload, including flow ID and execution ID where relevant. - External Request ID — an identifier you pass in from your own SDK calls to correlate a Descope event with your application's logs. > [!NOTE] > The default retention period for audit logs in the Console is 30 days. If you need longer, stream them out with an Audit connector before that window closes. ## Key terms - Project-level event — scoped to a single project: logins, user and tenant changes, flow updates, role edits. - Company-level event — spanning the whole company, tagged `Level=Company`. - External Request ID — the identifier that correlates a Descope audit event with your own logs. ## Summary - That audit logs serve both debugging and compliance - The two event scopes and how to tell them apart - The three ways to query, and the fields you can rely on - The default retention window, and what it implies --- A short catalog of the issues that recur most. None of them are mysterious once you have seen them, and recognizing the shape of a problem is most of the work of resolving it — so this is less a troubleshooting procedure than a set of silhouettes. ## Recurring scenarios - 502s — somebody else's server failed to answer. Inside a flow that is almost always a connector, and Troubleshooting Logs capture the complete upstream response rather than a generic message, which is what tells you whether the fault is Descope's or the third party's. - Redirect mismatch — the address a user is sent back to does not match what is registered. Check Approved Domains, the OAuth Callback URL at the provider, and whether a custom domain moved one without the other. - Missing SSO attributes — the user signs in successfully and arrives with nothing attached. Either the identity provider is not sending the claim, or the attribute mapping on the connection does not name it correctly. - SCIM delays — SCIM is pushed by the identity provider on its own schedule. A change that has not appeared yet is usually waiting at the IdP rather than lost in Descope. - Token validation failures — most often a base URL that does not match the domain tokens were minted for, or a backend validating the refresh token where it meant the session token. - Flow routing loops — a condition whose input never changes between evaluations, so the run keeps taking the same branch back to where it started. Two patterns are worth drawing out, because they account for most of the time lost. The first is that a configuration mismatch rarely announces itself as a configuration error. A redirect mismatch surfaces as a provider error page the user screenshots and sends you; a base URL mismatch surfaces as tokens that look fine and are rejected anyway. In both cases the error names the symptom and not the cause, so the useful instinct is to ask what recently changed about a domain rather than to read the message literally. The second is that "nothing happened" is itself evidence. A user who stalls mid-flow leaves a `LoginStarted` with no completion, and a SCIM change that never arrives leaves no event at all. An absence tells you which system to go and ask, which is why the previous lesson's distinction between the two logs matters more than any individual error string. > [!NOTE] > Before assuming a bug, establish which half of the journey broke. A flow that never finished is a Troubleshooting Logs question; a flow that finished and left the user without the access they expected is an authorization question, and the token itself will tell you which. ## Key terms - Redirect mismatch — a return address that does not match what is registered, at the provider or in Approved Domains. - Attribute mapping — the per-connection translation from the identity provider's claims to Descope's user fields. - Routing loop — a flow returning repeatedly to the same branch because the value its condition reads never changes. ## Summary - The six issues you are most likely to meet, and how to recognize each - That a configuration mismatch usually reports a symptom rather than its cause - Why an absent event is evidence, and which log an absence points you at - How to tell a flow that broke from a flow that finished with the wrong result --- An escalation moves faster when it arrives complete. Most of the delay on a support ticket is not diagnosis — it is the round trip where somebody asks which project, which user, and when, and waits a day for the answer. ## Collect before escalating - Project ID — which project, of the several a company usually has across environments. - Tenant ID — which customer, where the behaviour might be tenant-specific configuration. - User ID — who it happened to, rather than the login ID they typed. - Execution ID — which run of which flow, resolving straight to one record. - Timestamps — when, with a timezone, so the search window is unambiguous. - Request IDs — the correlation ID that ties every event from one request together. - Screenshots — what the user actually saw, including the error wording. - HAR files — the full browser-side exchange, for redirect, cookie and CORS problems. - Reproduction steps — what to do to see it happen again. The list sorts into three jobs. The identifiers narrow a search from an entire project to one record. The timestamps and request IDs make that search unambiguous when the identifiers alone would match several runs. And the screenshots, HAR file and reproduction steps describe the half of the story Descope's own logs cannot see — what the browser did, what the user was told, and whether it happens every time or once in twenty. > [!WARNING] > A HAR file is a complete record of a browser session, which means it contains tokens, cookies and anything else the page sent. Treat one as a credential: scrub it before attaching it, and do not paste it anywhere you would not paste a session token. Collect while the evidence still exists. Audit events are retained for 30 days by default, so a problem reported late in that window is one you should look up immediately rather than after the weekend — and if the answer matters beyond a month, the Audit connector covered earlier in this module is what keeps it reachable. ## Key terms - Execution ID — the identifier resolving to one specific run of one flow. - Correlation ID — the identifier tying every event produced by a single request together. - HAR file — a full capture of the browser's network exchange, and a credential in its own right. ## Summary - The nine items to gather before raising an escalation - The three jobs that list does: narrow the search, disambiguate it, and describe what Descope cannot see - Why a HAR file needs scrubbing before it is shared - That the retention window sets how long you have to collect any of it --- Audit logs tell you what happened at the identity level — a login succeeded, a role changed. Troubleshooting logs tell you what happened inside a flow while it was running: which step failed, what a connector returned, and why a user got stuck partway through. The Troubleshooting Logs page shows flow-level failures: connector errors, sign-in and sign-up action failures, and any other error tied to a specific step. For connector failures the complete error response is logged rather than a generic message, since that detail is usually what tells you whether the problem is on Descope's side or the third party's. ## Which log to reach for - Audit Trail — identity and compliance events: logins, admin changes, SCIM. Keyed by `correlation_id` in Data. Found on the Console's Audits page. - Troubleshooting Logs — what broke inside a flow, and where. Keyed by Flow Execution ID. Found under Audits & Troubleshooting. The fastest way to watch a flow fail is the Flow Runner: open the flow and click Run, and the runner writes error messages, console output, and every connector request and response to the Runner messages panel as it executes. For hosted flows, appending `&debug=true` to the URL turns on an in-browser debugger panel, which is what you want when an issue will not reproduce inside the Console. Inside a Scriptlet action, `console.log`, `console.warn`, `console.error`, and `console.debug` are captured automatically and appear in the runner messages, so you can leave your own breadcrumbs in custom logic. Flow Activity is the unified view. Rather than cross-referencing execution IDs between the audit log and the troubleshooting page by hand, it shows per-task status, timing, and error details for a whole execution in one table — Execution ID, Status, Task Type, Error Message, Connector ID, Tenant ID and more — with a free-text search matching across all of them. ## Key terms - Troubleshooting Logs — flow-level failure records, distinct from identity-level audit events. - Flow Execution ID — the key identifier for looking up a specific run. - Flow Activity — the unified per-task view of one flow execution. ## Summary - Which question each log type answers - That connector failures capture the full upstream response - How to watch a flow fail live, and how to debug a hosted one - Where to look when you would otherwise correlate IDs by hand ---