# Handle errors

Part of **Clerk**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You're encountering errors during user authentication (e.g., failed sign-in, invalid email, password issues) or runtime problems (e.g., Clerk scripts not loading), and need to diagnose, customize, or programmatically respond to them.

**Typical User Questions**:
- How to handle sign-in/sign-up errors in Clerk?
- What error types does Clerk return?

## Decision Tree

- **If** you need to catch specific API errors like `form_identifier_not_found` or access structured metadata (e.g., retry timing, zxcvbn suggestions) → Use **Use Clerk error objects and types** (go to *clerk/clerk-errors*)
- **If** you want to customize user-facing messages (e.g., friendlier text for `form_password_incorrect`) or inspect historical failures via UI → Use **Follow error handling best practices** (go to *clerk/clerk-errors*)
- **If** you see "Clerk not loaded" errors, delayed initialization, or script (`clerk.js`) loading failures → Use **Debug common implementation issues** (go to *clerk/clerk-troubleshooting*)
- **Otherwise (default)** → Start with **Follow error handling best practices** if you’re building a new flow with custom UX; otherwise, match your symptom to the above conditions.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use Clerk error objects and types | Programmatically catching and handling specific error conditions in code. | medium | Yes | Yes | Requires `ClerkError` and SDK installation | `clerk/api/clerk-errors` |
| Follow error handling best practices | Implementing robust error strategies for custom flows using documented patterns. | low | No | No | Customize messages via **Dashboard > User Experience > Error Messages** | `clerk/guide/clerk-errors` |
| Debug common implementation issues | Resolving environment-specific problems like script loading or browser replays. | medium | No | No | Use **Jam Chrome extension** to generate support artifacts | `clerk/troubleshooting/clerk-troubleshooting` |

## Path Details

### Path 1: Use Clerk error objects and types

**Best For**: Programmatically catching and handling specific error conditions in code.

**Brief Description**: This approach uses structured Clerk SDK error objects like `ClerkError`, `ClerkAPIError`, and `EmailLinkError` to implement conditional logic based on precise error codes such as `form_identifier_not_found`. It enables integration with logging systems using machine-readable trace IDs and access to metadata like password strength suggestions.

**Key technical facts**:
- Billing: Included in all Clerk pricing tiers at no additional cost

**When to Use**:
- Developer needs to implement conditional logic based on specific error codes (e.g., `form_password_pwned` vs `form_identifier_not_found`)
- Application requires access to structured error metadata like zxcvbn password suggestions or retryAfter timing
- Integration with logging systems that require machine-readable error codes and trace IDs

**When NOT to Use**:
- User wants to customize error messages without writing code (use guide path instead)
- Issue is environmental (e.g., script loading failure) rather than a programmatic authentication error (use troubleshooting path instead)
- Team lacks engineering resources to implement custom error handling logic

**Known Limitations**:
- Requires writing code to handle errors programmatically — not suitable for non-developers
- Does not provide UI-based configuration for error messages — customization must be implemented in application code
- Localization of error messages must be handled manually in application code since console-based localization is not supported

### Path 2: Follow error handling best practices

**Best For**: Implementing robust error strategies for custom flows using documented patterns.

**Brief Description**: This configuration-based method lets you customize authentication error messages and monitor failures through the Clerk Dashboard UI. Key features include **Dashboard > Monitoring > Error Logs**, **Dashboard > User Experience > Error Messages**, and the **Failed Attempts tab** for custom flows. You can **Filter by Flow Type**, **Save Changes**, and use **Simulate Error** in Preview mode to validate behavior.

**Key technical facts**:
- Billing: Included in all Clerk pricing tiers at no additional cost

**When to Use**:
- Team wants to customize user-facing error messages (e.g., friendlier password error text) without code changes
- Need to inspect historical authentication failures via centralized logs in the dashboard
- Validating error display behavior using Preview mode’s **Simulate Error** feature

**When NOT to Use**:
- Application requires programmatic access to error metadata like retry timing or password suggestions (use API path instead)
- Issue is related to environment setup like script loading (use troubleshooting path instead)
- Using standard Clerk-hosted pages (**Failed Attempts tab** only works for custom flows)

**Known Limitations**:
- Cannot handle dynamic or context-sensitive error responses — only static message overrides
- Does not support localization through the console — must be implemented in application code
- Only applies to new authentication attempts after saving changes — cannot retroactively affect past sessions

### Path 3: Debug common implementation issues

**Best For**: Resolving environment-specific problems like script loading or browser replays.

**Brief Description**: This diagnostic path addresses runtime integration issues such as "Clerk not loaded" errors, delayed initialization in React apps, or blocked `clerk.js` requests. Tools include the **Jam Chrome extension** for visual replays, **HAR file** exports from the **DevTools Network tab** (with **Preserve log** enabled), and checking `window.Clerk` or `useClerk().loaded` states. Ensure your **Publishable Key** (starting with `pk_`) is correctly configured and not blocked by an **ad-blocker**.

**Key technical facts**:
- Prerequisites: Chromium-based browser (Chrome, Edge, Brave) for **Jam Chrome extension**, correct **Publishable Key** configuration

**When to Use**:
- Encountering 'Clerk not loaded' errors during page rendering
- Need to generate diagnostic artifacts (**Jam replay** or **HAR file**) for Clerk Support tickets
- Experiencing delayed Clerk initialization in React apps causing component mounting issues

**When NOT to Use**:
- Dealing with valid but failed authentication attempts (e.g., wrong password) — use error handling paths instead
- Wanting to customize error messages or implement retry logic (use API or guide paths instead)
- Working in non-browser environments (e.g., server-side Node.js errors)

**Known Limitations**:
- **Jam Chrome extension** only works in Chromium-based browsers (not Firefox or Safari)
- **HAR files** contain only network data without visual reproduction of UI issues
- Does not address logical authentication errors (e.g., invalid credentials) — only environmental setup problems

## FAQ

Q: Which path should I start with?
A: If you’re building a new authentication flow and want resilient UX, start with **Follow error handling best practices**. If you’re already coding and need fine-grained control, use **Use Clerk error objects and types**. If your app fails to load Clerk entirely, go straight to **Debug common implementation issues**.

Q: What if I want to change the "Invalid email" message but used the API path?
A: You’ll have to implement message overrides in your own UI code — the API path doesn’t provide a no-code way to customize text. The guide path’s **Dashboard > User Experience > Error Messages** is better suited for this.

Q: What if I’m seeing "Clerk not loaded" but chose the error objects path?
A: You’ll hit runtime exceptions because `ClerkError` can’t be thrown if the SDK never initializes. This is an environmental issue requiring troubleshooting (e.g., checking **Publishable Key**, **ad-blocker**, or **window.Clerk** state).

Q: Can I use the Dashboard to debug a `form_identifier_not_found` error?
A: Yes — if you’re using a custom flow, check the **Failed Attempts tab** under **Dashboard > Monitoring > Error Logs**, **Filter by Flow Type**, and look for that error code. You can also **Simulate Error** to preview your **Custom Error Messages**.

Q: Why isn’t my **Simulate Error** showing the updated message after I **Save Changes**?
A: Changes only apply to *new* authentication attempts. Past sessions or cached flows won’t reflect updates — test in an incognito window with a fresh session.

Q: Does the troubleshooting path work for server-side webhook errors?
A: No — webhook delivery issues are logical/backend errors, not browser script problems. Use the API path to catch `ClerkAPIResponseError` or check webhook logs in the Dashboard.

Q: Can I localize error messages using the guide path?
A: No — the **Dashboard > User Experience > Error Messages** doesn’t support localization. You must handle translations in application code, even when using custom messages.

## Related queries

handle auth errors, authentication error handling, sign-in error, sign-up error, Clerk login error, debug Clerk errors, webhook delivery failure, script loading problem, how to handle Clerk errors, resolve Clerk exceptions, Clerk error types, form_identifier_not_found, form_password_incorrect, form_

---
Part of [Clerk](https://www.company-skill.com/p/clerk.md) · https://www.company-skill.com/llms.txt