Troubleshooting

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 toolsargs contains valid JSON Schema Draft-07
5. Check property names: Ensure exact spelling (baseurl, wssurl, apikey, userid, patientid, toolsargs)

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. Configure automatic reconnection in your implementation
3. Implement local buffer for unsent data
4. Check firewall and proxy that might block WebSockets

Configuration Issues

Invalid JSON schemas

Symptoms: Validation errors in toolsArgs

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 toolsArgs: Simplify schemas, use $ref for reuse
2. Optimize patientData: Use urls_historial instead of complete data
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: useEffect without dependencies
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
  }
}, [handleReport]); // Include dependency

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-component');
  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 toolsArgs
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

// Configure debug mode
<sofia-component 
  debug="true"
  // ... other props
>

Useful information for support

When contacting technical support, include:

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