Troubleshooting

Start troubleshooting from the message state and the subsystem involved. The Administration Console, /health, message diagnostics, logs, and—in commercial deployments—Prometheus/Grafana provide the primary operational signals.

HL7 intake and MLLP

Processing failures

PROCESSING_FAILED indicates an internal processing problem such as a mapping, script, or runtime failure. Open the Message Details view and inspect Last error together with the raw HL7 input.

• Check custom Groovy script logic and recent script changes.
• Verify required HL7 identifiers or fields used by the mapper.
• Check processing retry attempts and whether the processing circuit breaker is open Commercial.
• Correct the underlying cause before using administrative retry.

FHIR delivery failures

DELIVERY_FAILED indicates that conversion completed but downstream FHIR delivery failed.

• Verify fhir.server.base.url, authentication, network reachability, and TLS trust.
• Inspect the FHIR HTTP status and response text in Message Details.
• Check downstream FHIR server latency, HTTP 429/5xx responses, and timeout configuration.
• Review the FHIR delivery circuit breaker when repeated failures pause outbound delivery Commercial.

Rejected messages

REJECTED is commonly associated with semantic validation or workflow rules that intentionally block delivery. Review the validation result, rule severity, rule scope, and the clinical/workflow context that caused the rejection.

Database, retention, and disk growth

• Verify retention.processed.days, retention.filtered.days, retention.failed.days, and the purge interval.
• Check whether failed/rejected message volume has increased.
• Monitor available disk capacity and SQLite database growth.
• Keep db.path on local server storage, not NFS/SMB/network-mounted storage.
• Review backup retention and backup destination growth.

Administration Console unavailable

Check that FireSonic is running, verify management.host and management.port, confirm firewall/network access, and test /health. Also verify management authentication credentials when the HTTP endpoint is reachable but access is denied.

Scripts and semantic rules

• Compilation or initialization failures during startup prevent invalid script/rule generations from becoming active.
• Verify scripts.dir and semantic.rules.dir.
• Automatic script/rule hot reload requires the corresponding auto-reload setting and a commercial edition Commercial.
• For semantic rules, inspect the rules-engine state and loaded rule count in the Administration Console.

TLS and certificate problems

• Check the TLS Certificates Administration Console view for loaded and expiring certificates.
• Verify tls.certs.enabled=true and tls.certs.dir=./config/certs.
• Supported additional trust files are .pem, .crt, and .cer.
• FireSonic loads additional certificates during startup; restart FireSonic after changing them.

Slow processing or delivery

Measure where time is spent before changing worker or JVM settings. Common causes include downstream FHIR latency, network latency, expensive Groovy logic, terminology/external service calls, large Bundles, slow storage, and constrained CPU/memory.

Use the Performance and Monitoring articles to establish the bottleneck before tuning the deployment.

Useful diagnostics