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

# SDK 3 - Error Codes Reference

> Complete reference for SDK initialization and runtime error codes

## Overview

When an initialization error occurs, users see a generic error message with a specific error code that can be copied and shared with support.

Users see the same message for all errors—only the error code differs. This keeps the user experience simple while allowing developers and support teams to identify the specific issue.

**Error Code Format:** `SDK_ERR_XXXX,` where the number indicates the category.

## Quick Reference

| Code Range | Category            |
| ---------- | ------------------- |
| 1000       | General/Unknown     |
| 1001-1006  | Authentication      |
| 1011-1014  | Agent Configuration |
| 1021-1024  | Data Loading        |
| 1031-1033  | Network/Connection  |
| 1041-1042  | Permissions         |

<Tip>
  Know your error code? Use the Quick Reference table above to jump to the relevant category.
</Tip>

## Authentication Errors (1001-1006)

### SDK\_ERR\_1001 - Authentication Failed

**Cause:** Token validation failed.

**Solution:** Verify your `fetchAuthentication` returns a valid token object.

```javascript theme={null}
fetchAuthentication: async () => {
  const token = await yourAuthService.getToken();
  return { token };
}
```

### SDK\_ERR\_1002 - Token Expired

**Cause:** Token has expired.

**Solution:** Implement token refresh:

```javascript theme={null}
fetchAuthentication: async () => {
  const token = await yourAuthService.getOrRefreshToken();
  return { token };
}
```

### SDK\_ERR\_1003 - Token Invalid

**Cause:** Token is malformed.

**Solution:** Check you're returning the correct token format from your auth service.

### SDK\_ERR\_1004 - Token Missing

**Cause:** No token provided.

**Solution:** Ensure `fetchAuthentication` returns `{ token: string }`:

```javascript theme={null}
// ✅ Correct
fetchAuthentication: async () => ({ token: 'your-token' })

// ❌ Wrong - missing token property
fetchAuthentication: async () => ('your-token')
```

### SDK\_ERR\_1005 - Anonymous Access Denied

**Cause:** Agent requires authentication.

**Solution:** Either provide `fetchAuthentication` or enable anonymous access in Agent Management Studio.

### SDK\_ERR\_1006 - URL Not Whitelisted

**Cause:** Current domain not in anonymous access safelist.

**Solution:** Add your domain in Agent Management Studio or use authenticated access.

## Agent Configuration Errors (1011-1014)

### SDK\_ERR\_1011 - Agent Configuration Missing

**Cause:** Agent not configured.

**Solution:** Verify the agent exists and is published in Agent Management Studio.

### SDK\_ERR\_1012 - Agent Not Found

**Cause:** No agent with specified `agentUid`.

**Solution:** Check for typos—the UID is case-sensitive:

```html theme={null}
<mindset-agent agentUid="Your-Exact-Agent-UID"></mindset-agent>
```

<Warning>
  Agent UIDs are case-sensitive. `my-agent-uid` and `My-Agent-UID` are different agents.
</Warning>

### SDK\_ERR\_1013 - Agent Configuration Invalid

**Cause:** Agent configuration is corrupted.

**Solution:** Review settings in Agent Management Studio or recreate the agent.

### SDK\_ERR\_1014 - Agent Inactive

**Cause:** Agent is disabled or unpublished.

**Solution:** Activate the agent in Agent Management Studio.

## Data Loading Errors (1021-1024)

### SDK\_ERR\_1021 - Application Model Load Failed

**Cause:** Invalid `appUid` or application deleted.

**Solution:** Verify the ID in your `init` call:

```javascript theme={null}
window.mindset.init({
  appUid: 'your-correct-app-uid', // Check this
});
```

### SDK\_ERR\_1022 - User Model Load Failed

**Cause:** User profile couldn't be loaded.

**Solution:** Verify the auth token corresponds to a valid user.

### SDK\_ERR\_1023 - Agent Model Load Failed

**Cause:** Agent data couldn't be loaded.

**Solution:** Check agent setup is complete in Agent Management Studio.

### SDK\_ERR\_1024 - Required Models Not Loaded

**Cause:** Multiple data loads failed.

**Solution:** Check network connection and refresh the page.

## Network Errors (1031-1033)

### SDK\_ERR\_1031 - Network Timeout

**Cause:** Request took too long.

**Solution:** Check internet connection and try again.

### SDK\_ERR\_1032 - Network Connection Failed

**Cause:** No connection to Mindset AI services.

**Solution:** Verify internet connectivity and firewall settings.

### SDK\_ERR\_1033 - Firestore Connection Failed

**Cause:** Database connection failed.

**Solution:** Check the following:

* Internet connectivity
* Firebase status at [status.firebase.google.com](https://status.firebase.google.com)
* Firewall allows `*.firebaseio.com` and `*.googleapis.com`

## Permission Errors (1041-1042)

### SDK\_ERR\_1041 - Firestore Permission Denied

**Cause:** User lacks permission to access data.

**Solution:** Check user roles and permissions in Agent Management Studio.

### SDK\_ERR\_1042 - Application Access Denied

**Cause:** User not authorized for this application.

**Solution:** Verify user access settings in Agent Management Studio.

## General Error

### SDK\_ERR\_1000 - Unknown Error

**Cause:** Unexpected error.

**Solution:** Check browser console for details and contact [support@mindset.ai](mailto:support@mindset.ai) if issue persists.

## Error Display Behavior

The SDK handles errors differently depending on when and where they occur:

| Error Type         | Display                               | User Action                |
| ------------------ | ------------------------------------- | -------------------------- |
| **Initialization** | Full-screen overlay with error code   | Copy code, contact support |
| **Conversation**   | In-chat message after 10 auto-retries | Click "Retry" button       |

<Note>
  The SDK automatically retries conversation errors up to 10 times before showing the error UI, handling most transient network issues silently.
</Note>

## Reporting to Support

When contacting [support@mindset.ai](mailto:support@mindset.ai), include:

<Steps>
  <Step title="Error Code">
    The specific error code (e.g., `SDK_ERR_1012`)
  </Step>

  <Step title="Page URL">
    The URL where the error occurred
  </Step>

  <Step title="Browser Information">
    Browser name and version (e.g., Chrome 120, Safari 17)
  </Step>

  <Step title="Console Logs">
    Any additional errors from browser developer tools (press F12 → Console tab)
  </Step>

  <Step title="Steps to Reproduce">
    What you did immediately before the error appeared
  </Step>
</Steps>

<Tip>
  **How to copy console logs:**

  1. Open browser developer tools (F12 or right-click → Inspect)
  2. Go to the Console tab
  3. Right-click in the console and select "Save as..." or copy the error messages
</Tip>

## Common Error Patterns

### Authentication Issues (1001-1006)

**Most common cause:** Token format is incorrect or `fetchAuthentication` doesn't return the right structure.

**Quick check:**

```javascript theme={null}
// Your fetchAuthentication should return this exact format:
{ token: 'your-token-string' }
```

### Agent Not Loading (1011-1014)

**Most common cause:** Typo in `agentUid` or agent not published.

**Quick check:**

1. Copy the agent UID directly from Agent Management Studio
2. Paste it into your code (don't type it manually)
3. Verify the agent is published (not draft)

### Network Problems (1031-1033)

**Most common cause:** Firewall blocking Firebase or network connectivity issues.

**Quick check:**

1. Can you access other websites?
2. Are you behind a corporate firewall?
3. Check [status.firebase.google.com](https://status.firebase.google.com) for outages

## Troubleshooting Workflow

<Steps>
  <Step title="Note the error code">
    Copy the error code shown to the user (e.g., `SDK_ERR_1012`)
  </Step>

  <Step title="Find the error above">
    Use the Quick Reference table to locate your error category
  </Step>

  <Step title="Check the solution">
    Follow the specific solution steps for your error code
  </Step>

  <Step title="Check browser console">
    Open developer tools (F12) and check the Console tab for additional details
  </Step>

  <Step title="Contact support if needed">
    If the solution doesn't resolve the issue, contact [support@mindset.ai](mailto:support@mindset.ai) with the information listed in "Reporting to Support"
  </Step>
</Steps>

## Error Code Categories Explained

### Authentication (1001-1006)

Errors related to user authentication, token validation, and access control.

### Agent Configuration (1011-1014)

Errors related to agent setup, publishing status, and configuration validity.

### Data Loading (1021-1024)

Errors that occur when the SDK tries to load application, user, or agent data.

### Network/Connection (1031-1033)

Errors related to network connectivity, timeouts, and database connections.

### Permissions (1041-1042)

Errors related to user permissions and access rights.