Diagnose a red scan
Every rejection reason the door can produce, what it means, and who fixes it.
Owned by Door Staff · 15 steps · about 18 minutes
Why this exists
The reason codes are a closed set. There are thirteen of them and the scanner can never invent a fourteenth, which is what makes it possible to train a door on them exhaustively in one sitting. A red scan is never 'the system is being weird'; it is one of thirteen specific statements about that credential, recorded in the scan log with a timestamp and a reader.
They are produced in a fixed order, and the order is itself the diagnosis. The pipeline runs: parse the payload, then verify the signature or the time-based code, then check the revocation blacklist, then the pass status, then whether the order is actually paid, then whether the event is inside its door window, then the zone, then anti-passback. The first gate that fails is the one you are shown.
Two codes can also appear before their place in that order, and one of them means something different when they do. The pipeline splits on which kind of credential was scanned (access/service.py:1270), and each half has an early exit:
- Already Scanned, on the QR path only, fires right after the time-code check — before paid, event and zone are looked at at all. That is the cross-reader replay guard, and it is the good kind of early: it stops the second door before anything else is considered.
- Wrong Zone, on the signed-pass path, fires right after the signature, when the zones written into the payload do not match the zones on the issued pass. A pass is re-issued rather than edited when its zones change, so those two can only disagree if the payload was altered after issuance. This wrong-zone is not "right guest, wrong door" — it is a credential whose claims do not match the pass it names, and the guest at the barrier may not be the person it was issued to.
So the free inference holds for the ordinary wrong-zone red — signature valid, pass live, order paid, event open — but only for the one raised at the zone gate. If the guest scanned a signed pass rather than a live QR code, a wrong-zone red may have skipped every one of those checks. When a wrong-zone red comes off a saved or forwarded pass rather than the wallet's live screen, treat it as a credential question and call a manager, not as a door mix-up.
The design intent behind showing a reason at all, rather than a generic refusal, is that most reds have a legitimate answer at the door. Listed for sale means the guest has their ticket on the exchange and needs to delist it. Code expired means their screenshot is stale and they should open the live wallet page. Ticket not paid usually means a refund. Only a handful are genuinely 'this person is not getting in', and you should be able to tell those apart in a second.
What you must not do is escalate by improvising. There is no override on the scanner. If a guest needs to come in and the pass says otherwise, the sanctioned route is a manager and the guest-list walk-in override, which is recorded as an override with a named authoriser and a reason.
Before you start
- An employee session and a red scan in front of you.
- A manager or admin reachable for the escalations at the end.
Practise with
| Persona | Password | Note | |
|---|---|---|---|
| door_staff | door@club.test | door123 | door shift account: scanner + guest list, nothing else |
| venue_manager | manager@club.test | manager123 | shift lead: implies door_staff, plus intake, sales, guest list, marketing |
| admin | admin@club.test | admin123 | the only account that can touch money, identity and contracts |
| member | member@club.test | member123 | holds a seeded pass and membership card to practise scans against |
Steps 1–8 — Door Staff
their manual →-
1Read the red screen out loud to the guest before doing anything else. The large text is the human wording of the reason code; the reason code itself is in the Recent scans row underneath.Expected result One of: Unreadable Pass, Invalid Signature, Unknown Pass, Code Expired, Pass Revoked, Ticket Resold, Listed For Sale — Suspended, Ticket Not Paid, Event Not Active, Wrong Zone, Already Scanned, Not Checked In.Watch out for Saying the reason out loud is not a courtesy, it is the fastest triage you have. Half of these the guest can fix on their own phone in ten seconds once they know which one it is.
-
2Handle the three that mean 'the thing you scanned was not a real credential'. Unreadable Pass means the string was not a payload at all — usually a partial paste or a scuffed scan; try again. Invalid Signature means it was payload-shaped but the HMAC did not verify — a forgery, or a credential signed with a key that has since been marked compromised. Unknown Pass means the serial simply is not in the database.Expected result Unreadable Pass resolves on a clean re-scan. The other two do not.Watch out for Invalid Signature is the one to escalate rather than retry. A whole run of them at once usually means an admin marked a signing key compromised mid-shift, not that you have a queue of counterfeiters.
-
3Handle Code Expired. This only happens on the QR path and it means the eight-digit code was outside the fifteen-second step and its one-step tolerance. Ask the guest to open their live wallet page rather than a saved image, and scan again.Expected result A fresh code scans green.Watch out for There is a second, subtler cause: the same code already scanned green on a DIFFERENT reader within the same time step. That is a deliberate cross-reader replay guard and it surfaces as Already Scanned, not Code Expired — two people cannot walk two doors on one code.
-
4Handle the three ownership reasons. Pass Revoked means this credential was killed — refunded, resold, or revoked by an admin — and revocation is terminal, so it will never work again. Ticket Resold is what an old NFC payload shows after a transfer: the ticket is fine, but it belongs to somebody else now. Listed For Sale — Suspended means the guest currently has this exact ticket on the resale exchange.Expected result The guest recognises which of the three applies to them.Watch out for The suspended one has a real fix and is worth knowing: listing a ticket suspends its pass on purpose — you cannot sell it and also walk in on it. If the guest delists it, the same pass is restored and scans green. Nobody at the door can do that for them; it is their own listing to pull.
-
5Handle Ticket Not Paid. The pass is fine, but the order behind it is not in a paid state — nearly always a full refund, occasionally a checkout that never completed.Expected result A red that a manager can confirm from the order.Watch out for Partially refunded orders still scan green. If you see Ticket Not Paid, the whole order went, not one ticket of four.
-
6Handle Event Not Active. The credential is valid but you are outside the event's door window. A pass scans inside the window when the event is announced, on sale or sold out, and any time while it is in progress; before doors open or after teardown it goes red.Expected result A red that resolves by itself once doors open.Watch out for This is the most common red of the evening and it is almost always a clock question, not a ticket question. Check the event's doors-open time before you start telling people their ticket is broken.
-
7Handle Wrong Zone and the two anti-passback reasons, which are covered in detail in the scanner-screen workflow: wrong reader for the ticket, already inside, or trying to leave without having entered.Expected result You can name which of the three you are looking at without thinking.Watch out for Wrong Zone on a credential that worked ten minutes ago on the same reader means somebody presented a re-signed payload — the zones on the pass row are authoritative and a payload claiming different ones is rejected.
-
8When the guest genuinely should come in and the pass says otherwise, stop scanning and go to the guest list. Search their name — comps, plus-ones and prior overrides all live there.Expected result Their entry, or nothing.Watch out for If there is nothing, the next step is a manager and a recorded walk-in override, not a decision by you. The scanner has no override control by design.
Steps 9 — Member
their manual →Is the guest at the window, and usually holds the fix on their own phone.
-
9As the guest, do the two things that fix most reds without anybody's help: open your live wallet page rather than a saved screenshot, and check the status shown on the pass itself.Expected result Your passes with status active, suspended or revoked, and a QR that is regenerating rather than frozen.Watch out for A suspended pass means you listed that ticket on the exchange. Delist it and the same pass is restored — nobody at the door can do that for you, and arguing about it at the window costs you your place in the queue.
Steps 10–12 — Venue Manager
their manual →Looks the scan up in the log and decides whether the guest gets in another way.
-
10As the manager, look the scan up rather than taking anyone's word for it. Filter by event, by reader, or by result and reason.Expected result The exact scan with its reason code, method, direction, latency and reader.Watch out for Scan logs are the record you will be asked for weeks later about capacity or comps. They are written on every scan, red ones included — a red is evidence, not a discarded attempt.
-
11If the reason was Pass Revoked or Ticket Resold, check the Revocation list panel to see the serial, the reason and when it happened.Expected result The blacklisted serial with reason resold, refunded, admin_revoke or superseded.Watch out for You cannot un-revoke anything from here, and neither can an admin — revocation is terminal by design. The guest's route back in is a new credential, not a repaired old one.
-
12If the reason was Ticket Not Paid, open the order to confirm the refund and see who processed it.Expected result The order with its status and refund history.Watch out for You can read this page but you cannot issue a refund from it — refunds are admin-only. Confirming what happened is your job; reversing it is not.
Steps 13–15 — Admin
their manual →Owns the tools that reproduce a red on demand and the keys behind every signature.
-
13As an admin, reproduce a red deliberately when you are training staff or chasing a report. Simulate a scan against a ticket and a reader, optionally tampering the signature or the zone.Expected result A real scan envelope and a real scan_logs row, produced without a phone.Watch out for This writes genuine log rows. Do it on a demo event, or your training session shows up in the night's door numbers.
-
14When somebody insists their QR is correct, use the code oracle to see the previous, current and next valid codes for that ticket.Expected result Three codes and the step boundaries.Watch out for If the guest's code matches the previous or next step it was a timing issue and a re-scan fixes it. If it matches nothing, they are not holding the credential they think they are.
-
15For a run of Invalid Signature reds, check the Signing keys panel: rotation keeps old payloads working because retired keys still verify, but a key marked compromised fails every payload signed with it.Expected result Keys with status active, retired or compromised.Watch out for Marking a key compromised is a venue-wide event. Every wallet pass signed under it dies at once — never do it mid-shift to test something.