Appearance
Troubleshooting: Analyzer Issues
Diagnose and fix analyzer integration problems: connectivity, authentication, barcode matching, and result parsing.
Quick checklist
| Step | Check |
|---|---|
| 1 | Plan includes analyzer integration |
| 2 | Device exists and is not revoked |
| 3 | API key correct in middleware |
| 4 | HTTPS connectivity from analyzer PC |
| 5 | Barcode on sample matches invoice |
| 6 | Invoice status allows result entry |
HTTP 401 Unauthorized
| Cause | Fix |
|---|---|
| Missing header | Add X-Analyzer-Key: <key> |
| Wrong header name | Must be exact X-Analyzer-Key |
| Revoked device | Create new device; update middleware |
| Typo in key | Re-copy key from device creation |
Test: GET /integrations/v1/health with key header.
HTTP 422 Unprocessable Entity
Parse or matching failure. Response includes logId:
json
{
"message": "Could not match barcode SAMPLE-12345.",
"logId": "abc-guid"
}| Cause | Fix |
|---|---|
| Barcode not in system | Verify invoice has sample with that barcode |
| Barcode format mismatch | Check leading zeros, prefixes |
| Wrong protocol | Set device protocol to match message format |
| Malformed HL7/ASTM | Validate message structure |
Find details in Admin → Analyzers → Logs using logId.
HTTP 400 Bad Request
| Cause | Fix |
|---|---|
| Empty body | Middleware must send raw message content |
| Wrong Content-Type | Use text/plain or application/hl7 |
Results imported but not visible
| Check | Action |
|---|---|
| Wrong invoice | Verify barcode → invoice mapping in log |
| Invoice status | May need manual review before display |
| Parameter mapping | Test code in message must match catalog codes |
| Pending review | Some configs require manual confirmation |
Connectivity issues
| Symptom | Fix |
|---|---|
| Connection timeout | Check firewall allows outbound 443 |
| SSL error | Install trusted CA on middleware PC |
| DNS failure | Use IP or fix DNS on analyzer PC |
| Proxy blocking | Whitelist API domain in proxy |
Protocol-specific issues
HL7
| Issue | Fix |
|---|---|
| Wrong message type | Send ORU^R01 |
| Encoding | Use UTF-8 |
| Segment terminator | CR (\r) not LF |
| Barcode in wrong field | Map OBR-3 or PID per device manual |
ASTM
| Issue | Fix |
|---|---|
| Checksum errors | Enable checksum in middleware |
| Frame numbering | Sequential frame numbers required |
| Barcode in O record | Verify sample ID field |
Plan feature blocked
403 on /lab/analyzers routes:
- Subscription plan does not include analyzer integration.
- Upgrade plan or contact platform admin.
Integration endpoint (/integrations/v1/results) still validates API key — device must exist.
Key rotation procedure
- Create new device in EaseLab.
- Copy new API key.
- Update middleware configuration.
- Test with health endpoint.
- Revoke old device.
Log analysis
| Log field | Meaning |
|---|---|
| Status | Success / Error |
| Barcode | Matched sample ID |
| Results count | Parameters imported |
| Raw payload | First N chars of message (for debug) |
| Error | Parse or match failure reason |