Troubleshooting

Solutions for common SofIA SDK issues including initialization errors, audio problems, and framework-specific fixes

This page covers symptom-based troubleshooting — start here when something isn’t working as expected. For the complete catalog of SDK error messages with exact console output, see the Error Reference.

Initialization Issues

Missing or invalid required properties

Symptoms: Component displays detailed error messages in console and fails to mount

Error message example:

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

  • baseurl: API base URL for backend communication
  • wssurl: WebSocket URL for real-time communication
  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
    Current value: "INVALID_BASE_URL"
    Current value: "INVALID_WSS_URL"
    Current value: "INVALID_API_KEY"

Solutions:

1. Invalid API key: Verify API key is correct and active
2. Invalid URL format: Ensure URLs start with https:// (baseurl) and wss:// (wssurl)
3. Missing properties: Confirm all required properties are provided
4. Invalid JSON Schema: Validate that template contains valid JSON Schema Draft-07
5. Check property names: Ensure exact spelling (baseurl, wssurl, apikey, userid, patientid, template)

Component doesn’t load

Symptoms: SofIA component doesn’t appear on the page

Common causes:

• Script not loaded correctly
• Missing or invalid API key
• Error in props configuration

Solutions:

1. Verify that the script loads without errors in the console
2. Confirm that apikey is configured correctly
3. Validate that baseurl points to the correct endpoint
4. Ensure the container element exists in the DOM

Authentication error

Symptoms: 401 or 403 error messages in console

Solutions:

1. Verify that your API key is valid and active
2. Confirm you’re using the correct endpoint (sandbox vs production)
3. Check that your IP is whitelisted if applicable
4. Contact support if the problem persists

Audio and Transcription Issues

Microphone audio not detected

Symptoms: Transcription doesn’t start or doesn’t detect voice

Solutions:

1. Browser permissions: Ensure the browser has microphone permissions
2. HTTPS required: WebRTC requires HTTPS connection in production
3. Audio device: Verify that the microphone is connected and working
4. Browser configuration: Check privacy and audio settings

Poor transcription quality

Symptoms: Transcribed text with many errors

Solutions:

1. Improve audio quality (closer microphone, less noise)
2. Speak clearly and at moderate speed
3. Configure the correct language in the SDK
4. Use headphones to avoid echo and feedback

Frequent WebSocket disconnections

Symptoms: Connection loss during transcription

Solutions:

1. Verify network connection stability
2. The SDK handles reconnection automatically. If disconnections persist, check your network stability and firewall/proxy settings.
3. Verify that no corporate proxy or firewall is terminating idle WebSocket connections

Report Generation Issues

Report not generating

Symptoms: Clicking the generate button produces no result, or handleReport is never called

Solutions:

1. Verify template and templateid: Both template and templateid must be set. If either is missing, the generate button won’t appear at all
2. Check template validity: Open the browser console with debug="true" and look for [Sofia SDK] Settings Error messages. Common issues include missing $schema, invalid JSON syntax, or a template exceeding 100 KB
3. Ensure sufficient conversation: The AI needs enough conversation context to extract data. If the conversation doesn’t cover the fields defined in your template, the report may be incomplete or generation may fail
4. Check network connectivity: Report generation requires an API call. Verify your baseurl is reachable and check for [Sofia SDK] API Error messages in the console
5. Verify callback is set: Ensure handleReport is assigned before the user clicks generate — see the framework-specific examples below

Report is incomplete or empty

Symptoms: handleReport fires but the report object is missing expected fields

Solutions:

1. Review your template schema: Fields listed in "required" will always be present but may contain generic or empty values if the conversation didn’t cover them
2. Add field descriptions: Use the description property in your JSON Schema to guide SofIA on what data to extract for each field
3. Check patientdata: Providing relevant patient context via patientdata improves extraction accuracy — see Patient Data
4. Enable debug mode: Set debug="true" and check for [Sofia SDK] API - messages that show the report generation lifecycle

Configuration Issues

Invalid JSON schemas

Symptoms: Validation errors in template

Solutions:

1. Syntax validation: Use a JSON linter to verify syntax
2. Schema header: Include "$schema": "http://json-schema.org/draft-07/schema#"
3. Data types: Verify that types match JSON Schema Draft-07
4. References: Ensure $ref point to valid definitions

Payload too large

Symptoms: 413 error or messages about size limit

Solutions:

1. Reduce template: Simplify schemas, use $ref for reuse
2. Optimize patientData: Include only data relevant to the current consultation, and use url fields in medical notes to reference external records instead of embedding full content
3. Segmentation: Divide large queries into multiple sessions
4. Compression: Remove unnecessary spaces and empty optional fields

Integration Issues

Callbacks not executing

Symptoms: handleReport or other callbacks don’t respond

Solutions:

1. Correct syntax: Verify that callbacks are valid functions
2. Context: Ensure that this is correctly bound
3. Previous errors: Check console for errors that prevent execution
4. Schema configuration: Confirm that required is configured appropriately

Framework-specific issues

React:

// Common issue: callback not assigned on mount
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
  }
}, []); // Empty array — assign once on mount

Angular:

// Common issue: property binding
@ViewChild('sofia', { static: false }) sofia!: ElementRef;

ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
}

Vanilla JS:

// Common issue: DOM timing
document.addEventListener('DOMContentLoaded', () => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = handleReport;
});

Performance Issues

Slow responses

Symptoms: Excessive time between Generate and handleReport

Solutions:

1. Network: Check connection latency to servers
2. Data: Reduce size of patientData and template
3. Specialty: Some specialties require more processing
4. Cache: Implement caching for similar queries

Excessive memory consumption

Symptoms: Slow browser or freezes after prolonged use

Solutions:

1. Clean sessions: Close unused sessions
2. Event listeners: Remove listeners when destroying components
3. References: Avoid circular references in callbacks
4. Reload: Implement periodic reload for long sessions

Debugging and Logging

Enable detailed logging

Add debug="true" to the SofIA component to activate verbose console output. All SDK messages are prefixed with [Sofia SDK].

<sofia-sdk
  debug="true"
  baseurl="https://..."
  wssurl="wss://..."
  apikey="your-api-key"
  userid="doctor-123"
  patientid="patient-456"
></sofia-sdk>

What debug mode logs

Debug mode emits messages organized by category:

Log category	Prefix	What it covers
Configuration	[Sofia SDK] Settings - ...	Template parsing, validation, fallback behavior
Authentication	[Sofia SDK] Auth - ...	API key validation, token refresh
API calls	[Sofia SDK] API - ...	Report generation lifecycle (started, completed, failed)
WebSocket	[Sofia SDK] WS - ...	Connection status, reconnection attempts

Error messages include a category suffix to help identify the source: configError, authError, apiError, settingsError, audioError, storageError, or webSocketError.

Filtering console output

In your browser DevTools, use the Console filter to isolate SDK logs:

1. Open DevTools (F12 or Cmd+Option+I)
2. Go to the Console tab
3. In the filter input, type [Sofia SDK]
4. Only SDK messages will be displayed, removing noise from your application and third-party libraries

Reading template logs

For template-specific debugging — including the full console log reference, validation checklist, and common issue resolution — see Clinical data schemas — Debugging your template.

Useful information for support

When contacting technical support, include:

• SDK version used
• Browser and version
• Complete error messages from console (filter by [Sofia SDK])
• Props configuration (without including API keys)
• Steps to reproduce the problem