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.

For symptom-based troubleshooting (e.g., “component doesn’t load”), see the Troubleshooting guide.

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
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 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

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.

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 for how to update each deprecated prop.