Troubleshooting

Scalpels cannot provision the repository

Confirm that the Scalpels team's GitHub connection is active and installed on the account that should own the deployment. Scalpels forks the public artisan-build/witness repository into a different connected account; the Artisan Build account uses the existing repository directly. If the target already has a repository named witness, it must be a fork of this source or moved out of the way.

Invitations or codes do not arrive

Send a test message from Setup and inspect the environment's mail logs. Confirm the recipient address, spam handling, and chosen mail transport. A verification code expires after ten minutes; request a fresh code after delivery is working.

The envelope has every signature but is not complete

Check that the managed queue is attached and a worker is healthy. Completion runs after commit and writes the final PDF to private object storage. Also keep the scheduler active: it recovers ready envelopes if the normal event path was missed.

A PDF will not upload or complete

Confirm that the source is one valid PDF no larger than 20 MiB or 100 pages, and that object storage is attached and writable. Review worker logs for rendering or storage failures. Do not retry by editing envelope state in the database.

An invitation or download link expired

A reminder invalidates the previous invitation token, so use the newest email. Completion download links last seven days; an authorised user can return to Witness for the stored completed document.

/verify finds no match

Use the exact final PDF produced by Witness, not the source PDF or a copy modified by another PDF tool. Verification reports only completed matches. The upload is hashed for the request and is not stored.

Deletion remains pending

Keep private object storage available and the scheduler running. Witness records failed file deletion for retry so that a transient storage failure does not silently orphan the workflow. Escalate only after reviewing repeated scheduler and storage errors.