> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptom, cause, and fix for the common TruU IDV problems: directory connection, link delivery, desktop webcams and phone handoff, SMS and email codes, knowledge questions, face references, ServiceNow event push, storage, and use case routing.

This page is for the admin or help desk lead with a stuck verification in front of them. When you finish, you have the likely cause and the fix, or the request ID and event IDs support will ask for.

Most problems trace back to a small set of causes: directory data quality, link delivery, camera access on desktops, or use case rule order.

## Directory connection

| Symptom | Likely cause | Fix |
| - | - | - |
| Validation fails right after running the setup script | The app registration is still propagating, or admin consent has not been granted yet | Wait a minute and retry validation; it succeeds once propagation completes. Confirm consent was granted in the correct tenant and that tenant ID, client ID, and client secret were copied exactly. |
| Admin consent button is greyed out or fails | The person running setup is not a Global, Application, or Cloud Application Administrator | Have a second person with one of those roles grant consent. The connection can be saved first and validated after. |
| Connection worked, then stopped | Expired or rotated client secret | Create a new secret on the app registration and update it under **Settings → Directory**. Watch **Settings → Credential health** for expiry warnings. |
| Groups missing from the rule picker | The group catalog refreshes on a schedule; a group created minutes ago may not be listed yet | Wait and reopen the picker, or search by name. Membership itself is looked up live at verification time, so a user added to an existing group is matched immediately. |

See [Microsoft Entra ID](https://docs.truu.ai/idv/connect/directory/entra-id.md) for the full setup.

## Verification links

> [accordion] User reports the verification link is expired
>
> Links are short-lived by design: 30 minutes for Helpdesk, 1 hour for Credential reset, 7 days for Onboarding. Have the agent send a fresh link from the help desk app; requesting a link for the same person and use case while one is still active reuses it and resets its expiry rather than creating a duplicate. If links routinely expire before users open them, check the delivery channel and whether the agent is sending the link before the caller is ready to act on it.

> [accordion] User sees 'Already open on another device or browser'
>
> Where exclusive sessions are enabled for your workspace, each link is held by the first browser that opens it. This blocks link forwarding, but it also fires when a user opens the link on a laptop and then switches to a phone. Have the user close the page on the first device, wait about a minute, and reload the link. If the first device is unavailable, send a new link. The QR handoff on the verification page moves to a phone without triggering this, so prefer it over opening the link twice.

> [accordion] Link never arrives
>
> Check the request's timeline for a link delivered event versus a delivery failed event. For SMS, the most common cause is a directory phone number that is not in E.164 format. For email, check the recipient's spam folder and confirm your email security gateway is not quarantining the message. Email delivery is occasionally delayed by a minute or two; the resend works and refreshes the same link.

> [accordion] User opened the link but the request shows as not started
>
> The user may have opened the link in an in-app browser or a preview pane that pre-fetched the page. Ask them to open the link directly in the device's browser. Confirm on the request timeline whether a started event exists.

## Camera: desktop webcams and phone handoff

This is the most common source of failed Face and Proofing steps. Desktop webcams frequently fail capture: the page loops on "move closer" and "move further", or the camera never starts because the browser window is narrow enough to render the mobile layout. Phone QR handoff succeeds where the webcam does not.

> [!TIP]
>
> Recommend the phone by default. Brief agents to tell callers "scan the QR code with your phone" rather than "use your laptop camera". The handoff keeps the same request and link.

| Symptom | Likely cause | Fix |
| - | - | - |
| "Move closer" and "move further" loop on a laptop | Low-resolution or wide-angle webcam, poor lighting, or the user is too far from the screen | Hand off to the phone with the QR code. If the desktop is the only option, bring the face to about arm's length in even front light. |
| Camera never starts on desktop | The browser window is narrow and the page rendered as mobile, or camera permission was denied earlier | Maximize the window and reload, or allow camera access in site settings. Or hand off to the phone. |
| Camera prompt never appears | Camera permission previously denied for the site, or an endpoint management setting blocks it | Allow camera access for `verify.truu.ai` in browser site settings and reload. On managed devices where MDM blocks the camera, use the phone handoff. |
| Nothing happens on the Windows lock screen | Camera permission is not available on the lock screen | Phone handoff is the path there; the QR code is shown on the lock screen page. See [Windows agent enrollment](https://docs.truu.ai/idv/use-cases/device-enrollment.md). |
| Black screen where the preview should be | Another app holds the camera, or an in-app browser without camera support | Close other camera apps; open the link in Safari on iOS or Chrome on Android rather than an embedded webview. |
| Camera starts, then the Face or Proofing step fails before capture on a corporate laptop | SSL inspection on the corporate proxy is breaking the liveness stream or the vendor SDK | Allowlist the hosts on [Network requirements](https://docs.truu.ai/idv/security/network.md), or hand off to a phone off the corporate network. |
| Document capture repeatedly rejected | Glare, poor lighting, or the document outside the frame guide | Place the document on a dark non-reflective surface in even light and align it with the guide. |

## Factor failures

> [accordion] SMS codes fail or never arrive for many users
>
> Phone number formatting and coverage. SMS delivery requires E.164 (`+15551234567`); values like `555-123-4567` are rejected. SMS coverage is often far lower than email coverage, and many organizations restrict SMS. Check coverage of the mobile attribute in **Settings → Directory** before relying on the SMS factor, normalize numbers in the directory, and prefer Email in the primary column.

> [accordion] Email codes delayed or in spam
>
> Email codes are occasionally delayed; the resend works. If delivery problems are widespread, confirm your email security gateway allows the sending domain and check quarantine. Contact support to confirm sender authentication for your workspace.

> [accordion] User cannot resend a one-time code
>
> Resends are limited and a cooldown is shown on the button. This is expected, not a delivery fault. Have the user wait out the countdown; if they exhaust the resend budget, the flow falls back to the next column or the agent sends a fresh link.

> [accordion] Face is unavailable or fails for specific users
>
> The Face factor needs a reference photo. Users with none are routed to a fallback column. Two data-quality problems are common: directory photos are often stale (years old) or tiny (`thumbnailPhoto` at roughly 96 pixels), and both lower match scores. A photo deposited from a passed Proofing check matches far better. Configure the Face factor's reference sources so proofing-derived photos take precedence, and put Proofing in a fallback column so users without a usable photo create one. Check photo coverage under **Settings → Directory**.

> [accordion] Knowledge questions fail for legitimate users
>
> The attribute behind the question is empty or inconsistent. `department` in particular is often blank or formatted differently across business units, and many organizations keep the real org data in extension attributes. Check coverage and sample values in attribute mapping before enabling an attribute as a question source, map the extension attribute that actually holds the data, and disable attributes with poor coverage. See [Attribute mapping and coverage](https://docs.truu.ai/idv/connect/directory/overview.md#attribute-mapping-and-coverage).

> [accordion] Document proofing fails repeatedly
>
> Read the factor outcome reason on the request timeline. Common causes are capture quality, an unsupported or damaged document, a name that does not match the directory record, or a liveness failure. Have the user retry on a phone in better light. If failures persist for a legitimate user, follow your escalation procedure rather than creating repeated new links.

## ServiceNow connector

| Symptom | Likely cause | Fix |
| - | - | - |
| Verify Identity stopped working after an app upgrade | Upgrading the app clears its stored credentials | Generate a new connect link in **Settings → Connectors → ServiceNow** and connect again. |
| Test connection fails | Your instance is unreachable, the app is disabled, its credentials were cleared, or the app's OAuth client or integration user was deactivated | Confirm the instance is up and the app is enabled, then reconnect. |
| Connect says the instance refused an OAuth client-credentials token | ServiceNow turns the client-credentials grant off by default | Turn it on from the Connect page (one time per instance), then select **Connect** again. See [ServiceNow](https://docs.truu.ai/idv/connect/servicenow.md#connect-to-truu). |
| Work notes stop appearing | Your instance was unreachable when the event was sent | Events are still on the request timeline and in the audit trail. Run Test connection, check instance availability, and re-run the verification if needed. |

See [ServiceNow](https://docs.truu.ai/idv/connect/servicenow.md).

## Storage

| Symptom | Likely cause | Fix |
| - | - | - |
| Cannot add a store because your cloud team will not issue a bucket or credentials | Common; cloud teams often restrict new accounts | Use **TruU managed** storage for now. You can connect your own store later. See [Storage](https://docs.truu.ai/idv/connect/storage.md). |
| Store shows **Idle** | No writes have reached it yet | Run a Proofing check end to end. The badge turns **Live** on the first write. |
| Test connection fails | Wrong region or bucket name, or a credential without the access you selected | Check the credential's permissions on the bucket, then run **Test connection** again before **Connect**. |

## Wrong flow for someone

| Symptom | Likely cause | Fix |
| - | - | - |
| A person gets the wrong flow | Rules are checked top to bottom and the first match wins; a broader rule above the intended one matches first | In **Use Cases**, move the more specific rule above the general one. |
| A group rule never matches | The person isn't in the group, or the rule targets a similarly named group | Confirm membership in your directory; lookup is live, so there's no sync to wait for. Re-select the group in the rule. |
| The Catch All Flow runs instead of the flow you expected | The request was for a different use case, or no rule above **Everyone else** matches the person | Check which use case the request used in **Activity**, then that use case's rules. |
| Flow changes don't take effect | The flow wasn't saved | Open the flow and choose **Save flow**. |

## Still stuck?

**Activity** in the IDV Console is the fastest diagnostic tool: filter to the affected request or user and read the reason codes. See [Audit events](https://docs.truu.ai/idv/security/audit-events.md). When you contact [support](https://docs.truu.ai/idv/resources/support.md), include the request ID and the relevant event IDs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.