Troubleshooting

Gaps in the sequence

Abacus allocates before the order element is saved. If that save then fails, the number is spent and the sequence has a hole in it. Abacus is honest about this rather than pretending:

• Every allocation is recorded, so a hole is visible in Abacus → Numbers.
• Pro's Reuse abandoned numbers hands that number to the next order instead, once the allocation has sat unused past the reclaim window (an hour by default, so a customer still finishing payment cannot have their number taken).
• php craft abacus/numbers/reclaim sweeps them by hand.

The reclaim window matters. Set it to a minute and you will eventually take a number from an order that was merely slow.

An order still has its old cart-hash reference

Work down this list:

1. Is the scheme enabled? Abacus installs its scheme disabled on purpose.
2. Is "Number orders as they complete" on? With it off, Abacus only numbers on demand.
3. Did the order complete after you switched the scheme on? Abacus does not reach backwards — that is what Backfill is for.
4. Does a scheme's condition actually match? With several schemes (Pro), the first match wins and a scheme with no condition matches everything. If your catch-all is not last, it is swallowing orders meant for a later scheme.
5. Turn on "Log allocations" and complete a test order. The log says which scheme was tried and why it declined.

The same number twice

It should not be possible: uniqueness is checked against both commerce_orders.reference and the ledger, and the database backs that with a unique index on (schemeId, periodKey, number).

If you see it anyway, the usual cause is a reset policy without a date token in the format — {number} alone with a monthly reset produces 1 in January and 1 again in February. Abacus steps past the collision rather than issuing a duplicate, so what you actually see is a sequence that jumps rather than repeats. Add {yyyy}-{mm} to the format.

Numbering stopped after a deploy

Plugin editions live in project config. If config/project/project.yaml gets re-applied with the edition set to Lite, Pro-only behaviour — several schemes, skip lists, reclaim, backfill — stops quietly. Check Abacus → Schemes: only the first scheme will be doing any work.

Checkout is failing, not just misnumbering

Check If a number cannot be allocated. On Fail the order completion, an exception from Abacus escapes markAsComplete() with Commerce's own orderComplete:<id> mutex still held, and that order cannot be retried in the same request. Set it back to keep Commerce's reference unless you have a specific reason not to, and read Usage for the trade you are making.

Lock timeouts under load

The default lock timeout is 5 seconds. On a store taking many simultaneous checkouts, raise it — a scheme's mutex is held only for the few milliseconds it takes to render and record one number, so a timeout means contention, not slowness.

Getting help

Email justin@justinholt.com with the output of php craft abacus/numbers/status and, if allocations are being logged, the relevant lines.