Last updated: June 2026 — Added consent, 401, and evidence issues
This page covers common issues you may encounter while using AES prescription signing and how to resolve them.
| Possible Cause | Solution |
|---|---|
| Incorrect credentials | Reset your password via the Keycloak "Forgot password?" link |
| Account not activated | Contact your clinic administrator to verify your account is active |
| Wrong realm | You are logging into your clinic's realm (e.g. test-client), not veripath — check the login page URL |
| MFA code not accepted | Ensure your TOTP authenticator app clock is synchronised; try re-scanning the QR code |
| Browser cache | Clear your browser cache and cookies, then try again |
| Error | Cause | Solution |
|---|---|---|
| Consent checkbox not visible | "Issue Immediately" toggle is OFF | Toggle it ON to reveal the consent checkbox |
| "You must confirm your consent" on submit | Consent checkbox was not checked | Read the consent statement and check the box before submitting |
| Consent checkbox greyed out | Session may have expired | Log out and log back in |
| Error | Cause | Solution |
|---|---|---|
| "401 Unauthorized" | User session JWT expired or rejected | Log out and log back in. The system falls back to a service account automatically |
| "Certificate not found for clinician: [name]" | Clinician has no PKI certificate | Contact VeriPath to have a certificate issued — the Common Name must match get_full_name() exactly |
| "Signing service unavailable" | The aes-signer or aes-pki service is down |
Wait a few minutes and try again; contact VeriPath if persistent |
| "Timestamp service unavailable" | The aes-tsa service is unreachable |
Wait and retry; contact VeriPath if persistent |
| "Invalid prescription data" | Required fields are missing or invalid | Check all prescription fields (patient, medications, pharmacy) are complete |
| "HSM key not found" | Private key missing from SoftHSM | Contact VeriPath — the certificate may need to be re-issued |
| Prescription saves but shows "Signing Failed" | AES Portal returned an error | View the prescription detail page — the error message is shown in the AES Status section |
| PDF SHA-256 hash doesn't match | PDF may have been tampered with after signing | Compare the hash shown on the prescription detail page with the downloaded PDF's hash; contact VeriPath immediately if they differ |
| Issue | Cause | Solution |
|---|---|---|
| "Delivery failed" — HTTPS error | The pharmacy's delivery endpoint is unreachable | The system will auto-retry 3 times with exponential backoff. If still failing, check the pharmacy endpoint URL |
| "Delivery failed" — SMTP error | Email fallback delivery failed | Check the pharmacy's contact email address is correct |
| "Delivery pending" for too long | The pharmacy has not confirmed receipt | An administrator can retry manually via the AES Portal admin dashboard |
| Issue | Cause | Solution |
|---|---|---|
| "No signed PDF available" | Prescription has not been AES-signed yet | Check the prescription has been issued with "Issue Immediately" toggled ON |
| "Could not retrieve the signed PDF" | AES Portal unreachable or PDF file missing | Try again; if persistent, contact VeriPath |
| Evidence Summary shows empty actor fields | Prescription was signed before June 2026 (before evidence capture was implemented) | Only prescriptions signed after the update will have full actor evidence |
Evidence Summary shows python-requests as User-Agent |
IP/UA forwarding not configured | Ensure the GP Booking App is passing client_ip and client_ua to the AESClient |
Q: I'm a clinician — do I need to log into aes.veripath.co.uk?
A: No. All prescription activities happen within your clinic's GP Booking App at {your-clinic}.gp.veripath.co.uk. The AES Portal is infrastructure managed by VeriPath.
Q: What browsers are supported?
A: The latest versions of Chrome, Firefox, Edge, and Safari are supported.
Q: Can I use AES signing on a tablet or phone?
A: The GP Booking App's prescription form is usable on tablets. Mobile is not currently optimised for prescription creation.
Q: Where can I find training?
A: See the Prescription Workflow guide for step-by-step instructions, or contact your clinic administrator.
Q: What format are the signed prescriptions in?
A: Signed prescriptions are produced as PAdES-B-LTA compliant PDF files. This is a PDF/A-standard format with embedded long-term validation data (timestamp, OCSP/CRL). The signature remains verifiable for years after signing.
Q: Can the signed PDF be opened in any PDF reader?
A: Yes. Any standard PDF reader (Adobe Acrobat, Chrome PDF viewer, etc.) can display the document. Signature validation may require a tool that supports PAdES (e.g. Adobe Acrobat Pro, OpenPDF, or pyHanko CLI).
Q: How do I verify the SHA-256 hash of a downloaded PDF?
A: On macOS/Linux: shasum -a 256 downloaded.pdf. Compare the output with the X-Content-SHA256 response header or the PDF SHA-256 value shown on the prescription detail page.
Q: How long does the signing process take?
A: Typically 2-5 seconds from clicking "Save Prescription" to confirmation.
Q: What happens if the internet connection is lost during signing?
A: The signing operation will fail if the connection drops before completion. The prescription will not be partially signed — you can safely retry once connectivity is restored.
Q: What is the Evidence Summary JSON?
A: It's a downloadable file containing all seven data pillars required for eIDAS compliance: cryptographic (PDF SHA-256), identity (Keycloak sub, acr), forensic (IP, User-Agent), intent (consent text), temporal (signed timestamp), chain-of-custody (audit trail reference), and tamper evidence.
Q: Where are the signing keys stored?
A: All private keys are stored in SoftHSM2, a software-based Hardware Security Module. Keys never leave the HSM boundary. The solution is upgradable to a physical HSM for higher assurance.
Q: Who has access to my signing key?
A: Only you, after authenticating via Keycloak with MFA. VeriPath administrators can issue and revoke certificates but cannot extract or use your private key. The system attempts to use your own OIDC token for signing (sole control); if unavailable, a service account token is used as a fallback.
Q: Is the system audited?
A: Yes. Every signing event, PDF download, and delivery attempt is logged to a hash-chained audit trail (audit_chain.jsonl) with SHA-256 links between entries. See the Administration Guide for details.
Q: Can the system be used for other types of documents besides prescriptions?
A: Yes. The architecture supports multiple signature flows (patient agreements, consent forms, etc.) via path-based routing.
Q: Are AES-signed prescriptions legally valid?
A: Yes. Advanced Electronic Signatures are recognised under UK law (retained eIDAS Regulation). A signed prescription has the same legal standing as one signed with a wet signature. See Legal & Compliance.
Q: Does the system meet DSPT requirements?
A: Yes. The AES Portal provides audit logging, access controls, encryption in transit, evidence capture, and disaster recovery procedures to support Data Security and Protection Toolkit compliance.
Q: How long must signed prescriptions be retained?
A: Follow your organisation's record retention policy. The PAdES-B-LTA format ensures the signature remains verifiable for the long term without relying on external services.
Q: Can I download proof of signing for audit purposes?
A: Yes. Every signed prescription has a Download Evidence Summary button that returns a JSON document with all cryptographic, identity, forensic, and intent evidence captured at signing time.
If you encounter an issue not covered here: