Troubleshooting & FAQ
Quick fixes for the most common issues, then answers to the questions that come up most. If something here does not cover it, use the Report an issue button at the bottom of the page or register interest at getcql.com.
Common issues
Section titled “Common issues”Server not reachable
Section titled “Server not reachable”Confirm serve is running and the URL you are curling matches the host and port. In the drop-in container stack, Mercury is on port 8090, not 8080.
curl -fsS http://127.0.0.1:8080/api/health$evaluate returns 404 (library not found)
Section titled “$evaluate returns 404 (library not found)”POST the Library before evaluating. Canonicals resolve as Library/{id}|{version} — make sure the id and version match.
Subject or data not found
Section titled “Subject or data not found”Load the patient bundle first via POST /cqf/data/bundle, and make sure the subject id matches a resource in it. See Loading data.
Operation format errors (CLI)
Section titled “Operation format errors (CLI)”--operation must be libraryId:version:definition, e.g. Test:1.0.0:InDenominator.
File not found (CLI)
Section titled “File not found (CLI)”Confirm the --data, --valueset, and --cql/--elm paths exist and are readable.
State disappeared after a restart
Section titled “State disappeared after a restart”The container’s data directory was not mounted at /var/lib/mercury, so the replacement container started from an empty filesystem. Add a named Docker volume or host mount, then reload your libraries and bundles. See Mounting your data drive.
Bulk or connector route returns 403
Section titled “Bulk or connector route returns 403”Core-only builds keep Interoperability off by default. FHIR Bulk Data, Mercury-native /api bulk ingest/export, and Aidbox connector endpoints return 403 unless the Interoperability pack is explicitly enabled for a community build. Marketplace Core keeps add-on packs off.
Marketplace entitlement or edition mismatch
Section titled “Marketplace entitlement or edition mismatch”Marketplace binaries are built with the marketplace Cargo feature and report edition=marketplace. If startup fails with a License Manager or entitlement error, check the instance/task role permissions, AWS_MARKETPLACE_PRODUCT_SKU, AWS_LICENSE_MANAGER_KEY_FINGERPRINT, and AWS_MARKETPLACE_ENTITLEMENT_NAME. If startup says MERCURY_EDITION does not match the compile-time edition, verify the binary with mercury --no-banner edition and fix either the image/binary or the env var.
Security & operations FAQ
Section titled “Security & operations FAQ”Where does our data live?
Section titled “Where does our data live?”Community Edition runs entirely in your environment — your container, your host. Mercury does not phone home; data stays wherever you deploy it.
How is access controlled?
Section titled “How is access controlled?”Mercury Core does not ship authentication. Run it on a trusted network behind your own reverse proxy or API gateway for authn/authz. OAuth/OIDC, RBAC, and audit logging are part of the Security pack (in development).
How are secrets handled?
Section titled “How are secrets handled?”Core evaluation requires no external credentials or API keys — you hand it libraries, value sets, and data directly. Secrets management for connectors that do need credentials is part of the Security pack.
What’s the deployment model?
Section titled “What’s the deployment model?”Self-hosted single binary or Docker image. It composes with MCT and facility FHIR servers via docker-compose, and runs without a JVM.
Is data persisted? What about backups?
Section titled “Is data persisted? What about backups?”Yes — Mercury Core keeps durable local state that survives a restart when mounted on a volume. Back it up with your normal volume/host backup process. Replication and built-in backup/restore are part of the HA pack (in development). See Mounting your data drive.
What logging and monitoring are available?
Section titled “What logging and monitoring are available?”Structured logs (pretty or JSON) with configurable levels, plus /api/health and /api/ready. Metrics, dashboards, tracing, and lineage are part of the Insight pack (in development).
How do upgrades work?
Section titled “How do upgrades work?”Pull a new image or binary and restart. Zero-downtime rolling upgrades and node recovery are part of the HA pack (in development).
Does Mercury reach out to anything on its own?
Section titled “Does Mercury reach out to anything on its own?”No. It’s strictly request/response — you supply the libraries, value sets, and data, and it evaluates them. It doesn’t fetch terminology, code systems, or patient data from external services.
How is correctness assured?
Section titled “How is correctness assured?”Mercury is validated against the HL7 CQL 1.5.2 language test suite and benchmarked side-by-side against the reference engine for output parity. See Conformance & correctness.
What are the support boundaries?
Section titled “What are the support boundaries?”Community Edition is self-service through this documentation site and the docs repo issue forms where available. For access, support discussions, or anything that should not go in a public issue, register interest at getcql.com. Guaranteed response times and hands-on support are planned as a paid offering.