Troubleshooting¶
Start with the symptom table, then read the section it points to. Every message quoted here is the wording the system actually uses.
Never work around a compliance refusal
A refusal about a 4473, a NICS answer, the bound book or an FFL license is a federal control, not a bug. Fix the underlying record. If the control is genuinely wrong, get a manager, who has an audited override for exactly that case.
Symptom table¶
| What you see | Where | Go to |
|---|---|---|
| Cannot receive a firearm, supplier is not an FFL dealer | Receive Goods, Purchase Receipt | Receiving is refused |
| Cannot ship, destination FFL is expired or not on file | Create Order, invoice submit | Shipping is refused |
| Order will not submit, 4473 or NICS not clear | Register, Pending Order | An order is stuck awaiting a 4473 |
| A gun is missing from the bound book | Daily alert email, Serial No | A FastBound push failed |
| A gun is not on the website or the marketplace | Item, Serial No | A listing did not go out |
| Distributor quantities look wrong or frozen | Distributors hub, alert email | A distributor feed is stale |
| A card charge hung, or the amount is unclear | Register | A card charge went wrong |
| A serial shows as sold in the wrong place | Register, Firearms In Stock | A serial is sold in the wrong place |
Receiving is refused¶
What you see. One of three messages when you submit a receipt with a firearm line:
Cannot receive firearm from supplier '<name>' — not registered as FFL Dealer.
Open the Supplier form and use 'Search ATF' to populate FFL information.
Supplier '<name>' is marked as FFL Dealer but has no FFL Number on file.
Supplier '<name>' EZ Check status is '<status>'. Re-verify the FFL before
receiving firearms.
What it means. A firearm may only be acquired from a licensee, so the supplier record has to say who they are and their license has to have passed verification. The three messages are the three ways that fails: nobody has marked them as a dealer, they are marked but the number is blank, or the number is on file and its last check did not come back acceptable.
What to do. Open the Supplier form. Use Search ATF to look the license up and fill the fields in. If the license is on file already, run the verification again. A license that has genuinely expired needs a current copy from the supplier before anything is received.
Escalate to. A manager if the supplier insists the license is current and verification keeps failing. See FFL verification.
Shipping is refused¶
What you see. One of three messages:
Destination FFL <number> has no valid (unexpired) license on file — run Verify
FFL before shipping.
Destination FFL <number> is missing a complete address (street + a valid state)
— open the FFL and complete it (or run Verify FFL) before shipping, so sales
tax is computed correctly.
Destination FFL <number> is not on file — verify it first.
What it means. In order, the license we hold has expired, the record has no usable street and state, or there is no record at all. The address matters beyond the shipment, because sales tax is computed from where the gun goes.
What to do. Open the FFL record and run Verify FFL, which refreshes the name, address and expiry from the ATF. If verification cannot find it, ask the receiving dealer for a current copy of their license and enter it by hand.
For a Curio and Relic buyer the messages are different, because a Type 03 license cannot be looked up and a person confirms it instead:
C&R license <number> expired on <date>.
<number> is not a Type 03 (Curio & Relic) license — the fourth group must be
03, in the form 1-23-456-03-7C-89012.
A C&R gun must ship to the licensed premises, so a state or ZIP that disagrees with the license is refused as a C&R Address Mismatch.
Escalate to. A manager. Do not ship on a license the system has refused.
An order is stuck awaiting a 4473¶
What you see. On submit:
Cannot submit firearm transfer: 4473 form status is '<status>', must be
'Completed'.
Cannot submit firearm transfer: NICS status is '<status>', must be 'Proceed'.
Each message continues with what to do next, and the ending depends on how this store handles 4473s. With FastBound it tells you to click FastBound 4473, complete the form there and wait for the webhook to mark the order Completed. In Paper 4473 Mode it tells you to complete the paper form, run the background check, then click Record Paper 4473 on the payment screen.
There is a third message that catches a gun added, or a serial swapped, after the 4473 was finished:
Cannot submit: firearm serial(s) <serials> have no completed 4473 with NICS
Proceed on this order. Each firearm must clear its own 4473 first.
What it means. Every gun leaves against its own completed form and its own background check. The order-level status is not enough on its own.
What to do. Find the order on the Pending 4473 Orders report and read its NICS column. A Delayed order waits until it clears or until its Brady date arrives. A Denied order does not complete, and the gun goes back on the shelf. A missing 4473 means somebody needs to run it. If a gun was added after the fact, run a 4473 for that gun.
Escalate to. A manager. Managers have an audited override for a 4473 that is genuinely finished but stuck electronically. Every override lands on the Hand-Asserted 4473 Dispositions report with the name of who did it and the reason they gave.
A FastBound push failed¶
What you see. A daily alert email with the subject <n> FastBound record(s)
stuck unsynced, listing each acquisition or disposition and its error. Entries
tagged [needs human] will not retry themselves. On the record, the
FastBound Sync Error field holds the same text and the FastBound ID is
empty.
What it means. The bound book entry exists here but never reached FastBound. Retries run daily, so a transient network error clears on its own. A rejection does not: FastBound refused the data and will refuse it again.
What to do. Open the record and read the error. The common cause is a missing required field, which FastBound rejects outright. Fill it in and let the daily reconcile retry, or push it again from the record. On a Serial No, Sync with FastBound pushes that one gun.
To find divergence rather than failure, open Firearms In Stock and use Check FastBound differences, which scans in-stock guns field by field and lists any that disagree.
Escalate to. A manager same-day if the record is a disposition. A gun that has left the building with no bound book exit is a recordkeeping gap, not a sync backlog.
A listing did not go out¶
What you see. The gun is in stock here but is not on the site or the marketplace, and no error was shown at the time.
What it means. Pushes are queued and can fail after the click. Each channel records its own state on the Serial No or the Item:
| Field | What it tells you |
|---|---|
| GunBroker Push Pending | A listing went out and the result was never confirmed. A second attempt is blocked on purpose, because GunBroker enforces no uniqueness and a hopeful retry creates two live listings for one gun. |
| GunBroker Push Attempted At | When that unconfirmed attempt happened. The grace period runs from here. |
| GunBroker Delisted | Somebody ended this listing. No automatic path ever re-lists a gun carrying this flag. A person does, by pressing Send to GunBroker, which also clears it. |
| GunBroker Price Dirty | The price changed and GunBroker has not been told. The next sweep publishes it. |
| GunBroker Missing Count | How many consecutive sweeps found no such listing. |
For WooCommerce, failures surface as a message beginning WooCommerce sync
failed:, WooCommerce delist failed: or WooCommerce API error: followed by
the store's own reason, and the settings form's Last error field on the
Status tab keeps the most recent one.
What to do. Read Last error on the channel's settings page first. Then push the single item or serial again from its own form. Two specific refusals have specific fixes:
Check 'Publish to Dealer Portal' on the Item before sending it to the dealer
store.
Serial <serial> cannot be listed: <reason>.
The first needs the tick box on the Item. The second names the listing term that is unusable, most often a price or a duration.
Escalate to. A manager if a GunBroker push has been pending for more than a day, since the recovery scan should have settled it. See GunBroker and WooCommerce.
A distributor feed is stale¶
What you see. An alert email titled Distributor feed stale: <name> saying
how old the heartbeat is against a 90 minute threshold, that published drop-ship
quantities are no longer trustworthy, and whether the zero-stock interlock is on
or off. On the Distributors hub the quantity feed and
catalog heartbeats show the same age.
What it means. The distributor's quantity file has not refreshed. Anything we publish from it is a guess, and with the interlock on the system pushes those listings to zero stock rather than risk overselling.
What to do. Open the distributor's settings and read Last Sync Error. Run Sync Quantities Now by hand. Credentials that stopped working, a filename the distributor changed and a server that is down all look the same from here, and the error text separates them.
Escalate to. A manager, and a distributor rep if the error points at their end. Do not turn the zero-stock interlock off to make listings look healthy.
A card charge went wrong¶
What you see. Either the terminal never came back and the register is still waiting, or the sale went through with the amount split across more than one card and the totals do not look right, or a message saying the gateway moved money but the system could not record it.
What it means. Three different situations, and they are not interchangeable:
| Situation | What is true |
|---|---|
| Timed out or cancelled | The instruction may or may not have captured. The system follows the gateway's own record before deciding. |
| Partially approved | Part of the amount was taken. The register tracks how much of the card total remains and refuses a second charge that would exceed it. |
| Money moved, record failed | The gateway definitely took the money and the system definitely could not write it down. |
What to do. For a timeout, let the register finish resolving. It reads the outcome from the gateway rather than assuming. For a partial approval, take the remainder on another tender. The register will refuse an amount larger than what is left on the card total, and it will refuse a second charge on an invoice that is already fully paid by card.
For the third case, stop. The message tells you not to retry the refund or the void, because that would move money again, and to write down the invoice number for the back office. An alert email also goes out. Reconcile against the Payroc portal by hand before anything else is attempted.
Escalate to. A manager immediately for the third case. A refund or a void needs manager rights in any case.
A serial is sold in the wrong place¶
What you see. At the register, on a firearm line:
Serial <serial> already has a buyer on GunBroker — do not sell it at the
counter. Cancel this line.
Serial <serial> has bids in a GunBroker auction — it is promised to the high
bidder until the auction ends. Cancel this line.
From a web order, a serial row carrying a reservation error such as No Active
unreserved serial available for '<item>' to hold stock — staff action
required.
What it means. Another channel got there first. The register checks GunBroker before letting a listed gun be sold at the counter, and a gun with a live bid is promised to that bidder until the auction ends. On the web side, the order arrived and no free unit was available to hold for it.
What to do. Cancel the line and tell the customer. Do not sell a gun that another channel has taken, and do not end an auction that has bids to free a gun up. For a web order with no available unit, find a replacement unit or contact the buyer. The retry sweep re-attempts reservations that failed for a transient reason, but it deliberately does not retry a genuine out-of-stock.
The opposite case also happens: a gun that is sold or gone but still shows as in stock here. Run Sync Bound Book on Firearms In Stock. It lists every in-stock gun FastBound reports as disposed and offers to take them out of stock, and it withholds guns that are out on consignment, which are disposed in FastBound and still ours by design.
Escalate to. A manager before removing anything from stock, and before touching an auction that has bids.
Where alerts land¶
Operational alerts go to the addresses in Alert Recipients on FFL Settings, and to every System Manager when that field is empty. Repeated failures are throttled, so one broken thing sends one digest rather than one email per attempt. Stuck documents also get an assigned task on the document itself, raised once and only once until a person closes it. See Background jobs and Daily checks.