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

# Error Reference

> Complete reference of SofIA SDK error codes, messages, and resolution steps

This page documents every error the SofIA SDK can emit, organized by category. All errors are logged to the browser console with the prefix `[Sofia SDK]` when `debug="true"` is enabled.

<Info>
  For symptom-based troubleshooting (e.g., "component doesn't load"), see the [Troubleshooting guide](/sofia/en/sdk/troubleshooting).
</Info>

## Error categories

The SDK classifies errors into seven categories, each with a dedicated logger method:

| Category    | Prefix                             | Trigger                                                     |
| ----------- | ---------------------------------- | ----------------------------------------------------------- |
| `config`    | `[Sofia SDK] Configuration Error`  | Missing or invalid props, component won't mount             |
| `auth`      | `[Sofia SDK] Authentication Error` | Invalid API key, expired token (HTTP 401)                   |
| `api`       | `[Sofia SDK] API Error`            | Network failures, server errors, report generation failures |
| `settings`  | `[Sofia SDK] Settings Error`       | Template parsing failures, settings fetch errors            |
| `audio`     | `[Sofia SDK] Audio Error`          | Microphone access denied, audio recording failures          |
| `storage`   | `[Sofia SDK] Storage Error`        | LocalStorage unavailable, encryption failures               |
| `webSocket` | `[Sofia SDK] WebSocket Error`      | Connection failures, disconnections during transcription    |

## Configuration errors

### Missing required properties

**Console output:**

```
[Sofia SDK] Configuration Error - Missing or invalid required properties:

  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
  • baseurl: API base URL (only required for keys that need it)
    Current value: "undefined"

Component will not mount until all required properties are provided.
Documentation: https://omniloy.mintlify.app/en/sdk/required-properties
```

**Cause:** One or more of the required props (`apikey`, `userid`, `patientid`) is missing or empty — or, for a key that requires it, `baseurl` is missing.

**Resolution:**

1. Verify `apikey`, `userid`, and `patientid` are set on the `<sofia-sdk>` element
2. Check that values are not empty strings or `undefined`
3. For newer keys the endpoint is auto-resolved; if your key requires `baseurl`, ensure it is set and uses `https://`

### Missing session identifiers

**Console output:**

```
[Sofia SDK] Session Warning - Missing session identifiers:

  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
    Current value: "undefined"

Component will not mount without session identifiers.
```

**Cause:** `userid` or `patientid` is missing or empty.

**Resolution:**

1. Provide both `userid` and `patientid` as non-empty strings
2. These values should uniquely identify the current doctor and patient session

## Authentication errors

### Invalid API key (HTTP 401)

**Console output:**

```
[Sofia SDK] Authentication Error - Invalid API key provided. Please verify your API key is correct.
```

**Cause:** The `apikey` prop contains an invalid, expired, or revoked API key.

**Resolution:**

1. Verify the API key is correct and active
2. Confirm you're using the right key for your environment (sandbox vs production)
3. Check that the key hasn't been rotated or revoked
4. Contact support if the key should be valid

### Incorrect base URL (HTTP 404)

**Console output:**

```
[Sofia SDK] Configuration Error - Base URL is incorrect. Please verify your baseurl property points to the correct API endpoint.
```

**Cause:** The `baseurl` prop points to a non-existent endpoint.

**Resolution:**

1. Verify the URL matches your assigned environment
2. Ensure you're not mixing sandbox and production URLs
3. Check for typos in the URL

## Settings errors

### Template validation failed

**Console output:**

```
[Sofia SDK] Settings Error - Template validation failed
```

**Cause:** The `template` prop contains invalid JSON or is missing required schema keys (`$schema`, `type`, `properties`).

**Resolution:**

1. Validate your JSON syntax at [jsonlint.com](https://jsonlint.com)
2. Ensure the schema includes `"$schema": "http://json-schema.org/draft-07/schema#"`
3. Verify `"type": "object"` is present
4. Check that `properties` contains at least one field definition
5. See [Template validation checklist](/sofia/en/sdk/templates#template-validation-checklist) for details

### Fallback to server template

**Console output:**

```
[Sofia SDK] Settings Error - Using fallback template
```

**Cause:** The local `template` prop couldn't be parsed after three attempts (JSON.parse, prefix removal, Function eval). The SDK falls back to the server-configured template for your `templateid`.

**Resolution:**

1. Fix the local template JSON — this is usually a syntax error
2. Check for unescaped special characters in the template string
3. If passing programmatically, ensure you're passing a JSON string, not a JavaScript object

## API errors

### Report generation failed

**Console output:**

```
[Sofia SDK] API Error - Report generation failed: {error details}
```

**Cause:** The report generation process encountered an error during AI processing.

**Resolution:**

1. Check the specific error message for details
2. Verify network connectivity to the API server
3. Ensure the template schema is valid
4. If the error persists, retry after a few seconds
5. Contact support with the error message if the issue continues

### Network errors

**Console output:**

```
[Sofia SDK] API Error - {context}. Please contact support if this issue persists.
```

**Cause:** HTTP 5xx errors or network timeouts during API calls.

**Resolution:**

1. Verify internet connectivity
2. Check if the API endpoint is reachable
3. Look for CORS errors in the browser console
4. Verify firewall/proxy settings don't block the API domain

## Audio errors

### Microphone access denied

**Console output:**

```
[Sofia SDK] Audio Error - Microphone access denied
```

**Cause:** The browser's microphone permission was denied or the page is not served over HTTPS.

**Resolution:**

1. Check browser permissions — click the lock icon in the address bar
2. Ensure the page is served over HTTPS (required for WebRTC)
3. Verify the microphone hardware is connected and functional
4. In Chrome, go to `chrome://settings/content/microphone` to check site permissions

### Audio recording failure

**Console output:**

```
[Sofia SDK] Audio Error - {recording error details}
```

**Cause:** Audio recording failed due to hardware issues, codec problems, or browser incompatibility.

**Resolution:**

1. Try a different microphone
2. Close other applications that may be using the microphone
3. Test in a different browser (Chrome is recommended)
4. Check the browser console for more specific WebRTC errors

## WebSocket errors

### Connection failure

**Console output:**

```
[Sofia SDK] WebSocket Error - {connection error}
```

**Cause:** WebSocket connection to the transcription server failed or was rejected. The transcriber URL is provided automatically by the settings API (the `wssurl` prop is deprecated and ignored since v1.0.7).

**Resolution:**

1. Check network connectivity and firewall rules
2. Ensure WebSocket (`wss://`) connections are not blocked by proxy
3. Confirm your `apikey` is valid so the settings API can return the transcriber URL
4. Verify the page is served over HTTPS

### Disconnection during transcription

**Console output:**

```
[Sofia SDK] WebSocket Error - {disconnection details}
```

**Cause:** WebSocket connection dropped during active transcription.

**Resolution:**

1. Check network stability
2. The SDK attempts automatic reconnection — wait for it to reconnect
3. If disconnections are frequent, check your network infrastructure
4. Verify no proxy or firewall is terminating idle WebSocket connections

## Storage errors

### LocalStorage unavailable

**Console output:**

```
[Sofia SDK] Storage Error - {storage error}
```

**Cause:** Browser LocalStorage is unavailable (private browsing mode, storage full, or disabled by policy).

**Resolution:**

1. Check if the browser is in private/incognito mode — some features may not persist
2. Clear browser storage if it's full
3. Verify that LocalStorage is not blocked by enterprise policies or browser settings

## Input validation errors

These errors occur when user input fails security validation:

| Error message                                            | Cause                                    |
| -------------------------------------------------------- | ---------------------------------------- |
| `Input exceeds maximum length of {n} characters`         | Input text is too long                   |
| `Input contains only whitespace`                         | Empty or whitespace-only input           |
| `URLs not allowed in input`                              | Input contains URLs (blocked by default) |
| `Potentially malicious HTML/JavaScript content detected` | XSS patterns detected                    |
| `Potentially malicious SQL content detected`             | SQL injection patterns detected          |
| `Potentially malicious NoSQL content detected`           | NoSQL injection patterns detected        |
| `Invalid JSON format`                                    | Malformed JSON in a JSON-expected field  |

<Info>
  Input validation runs automatically on user input. These errors are security features and should not be suppressed. If legitimate medical text triggers a false positive, contact support with the specific text that was rejected.
</Info>

## Deprecation warnings

When using deprecated props with `debug="true"`, the SDK emits:

```
[Sofia SDK] DEPRECATED: "{propName}" prop is deprecated and has no effect. {migration message} This prop will be removed in v2.0.
```

See the [Migration Guide](/sofia/en/sdk/migration) for how to update each deprecated prop.