Launch Errors
SMART on FHIR launch errors can occur during the authorization flow, token exchange, or FHIR data retrieval. You should implement error handling for each stage to ensure that the Patient Chart can be launched successfully and that failures are visible and recoverable. Validate required parameters, monitor authorization and token responses, and log unexpected behaviors for troubleshooting.
Common Errors and Solutions
| Error Scenario | Description | Recommended Action |
|---|---|---|
Missing or invalid iss or launch parameter | The SMART launch URL must include both iss (FHIR server base URL) and launch (opaque context ID). | Verify that the launch URL includes these parameters and that their values are correct. |
Invalid or missing client_id | The token request is rejected because the client is not registered or the client_id is incorrect. | Confirm that your client is registered with Health Gorilla and that the correct client_id is used. |
Mismatched redirect_uri | The redirect_uri in the token request does not match the URI on file for your client. | Use a redirect_uri that exactly matches the one you registered. |
| Authorization code expired or already used | A code can only be used once and is valid for a limited time. | Restart the launch sequence and request a new code. |
| Missing or invalid scopes | The viewer cannot access FHIR data due to insufficient authorization. | Ensure that you include launch, openid, fhirUser, and patient/*.* (or user/*.*) in the initial authorization request. |
| HTTP 401 Unauthorized on FHIR calls | The access token is invalid or expired. | Refresh the token if available, or prompt the user to reauthenticate. |
| Viewer loads but displays no data | Access token lacks required scopes or user lacks permission. | Check that the access token includes the correct scopes and that the user has valid consent and authorization for the patient record. |
Debugging Tips
- Monitor redirect traffic and log all parameters received and sent during authorization.
- Log token responses, including scopes and expiration values, for debugging session issues.
- Use browser developer tools or network inspection to trace FHIR API calls made by the viewer.
- Contact Health Gorilla Support if errors persist or if server-side issues are suspected.