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

# Troubleshooting

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

<Info>
  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](/sofia/en/sdk/error-reference).
</Info>

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

  • 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: "INVALID_API_KEY"
    Current value: "INVALID_USER_ID"
    Current value: "INVALID_PATIENT_ID"
```

**Solutions**:

1. **Invalid API key**: Verify API key is correct and active
2. **Invalid URL format**: If your key requires `baseurl`, ensure it starts with `https://`. For newer keys the endpoint is auto-resolved — omit `baseurl`
3. **Missing properties**: Confirm all required properties (`apikey`, `userid`, `patientid`) are provided
4. **Invalid JSON Schema**: Validate that template contains valid JSON Schema Draft-07
5. **Check property names**: Ensure exact spelling (`apikey`, `userid`, `patientid`, `baseurl`, `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](#framework-specific-issues) 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](/sofia/en/sdk/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**:

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

**Angular**:

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

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

**Vanilla JS**:

```javascript theme={null}
// 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]`.

```html theme={null}
<sofia-sdk
  debug="true"
  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](/sofia/en/sdk/templates#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