Skip to main content

CVGo Exception Recovery

What to do when a CVGo POS Data record is stuck, fails, or doesn't reconcile. Use the Daily Cycle as the happy path and come here when something goes sideways.

Who this is for

Anyone running the daily CVGo workflow who has hit an error or a stuck record. Read CVGo Daily Cycle first if you're not yet familiar with the normal flow.

State map​

The cron jobs run every minute and automatically advance Draft → Validated → Posted, unless the record hits a config gate (most commonly an unconfigured MOP). A record can sit in Validated indefinitely with no error visible on the form — always check the Logs tab when something looks stuck.

Diagnostic — start here​

SymptomMost likely stateJump to
Upload itself failedPre-DraftUpload failures
Record stuck in Draft for more than a minuteDraftStuck in Draft
Record stuck in Validated, no error on screenValidatedStuck in Validated
Posting fails with a visible errorValidatedPosting failures
Reconciliation tab shows UnbalancedPostedUnbalanced reconciliation
Skipped transactions > 0 on the recordPostedSkipped transactions
Register Payments button missingPostedAlready paid

Upload failures​

File Hash already existing!​

Root cause: Same ZIP was already uploaded — files are deduped by hash on purpose. Recovery: Search existing CVGo POS Data records by date and station. You almost certainly already have this file. Don't: Rename or re-zip the file to bypass the check — that creates a true duplicate.

Upload succeeds but the record never appears in the list​

Root cause: Active company switcher is set to a different branch than the file is for; the new record is filtered out by the branch filter. Recovery: Switch to the correct branch (top-right). Or remove the company filter on the list view.

Stuck in Draft​

The validation cron runs every minute. If a record stays in Draft for more than ~2 minutes, validation has failed silently.

Where to look: Open the record > Logs tab > filter by Error.

Common causes​

Log entryCauseRecovery
XML parse error / not a valid CVGo exportThe ZIP is corrupted or contains non-CVGo filesGet a clean export from CVGo. Delete this record and re-upload the new ZIP.
Missing required XML fileZIP is missing the Periods or Transactions XMLSame — request a complete export and replace.
Permission / file-system errorsServer-side issue (disk full, perms)Escalate to IT. Do not retry.

After fixing the source file, re-uploading does not require deleting the old Draft record if the hash differs — just upload the corrected ZIP and remove the bad Draft. If the hash matches, you must delete the bad record first.

Stuck in Validated​

By far the most common stuck state. The posting cron skipped this record because something is gating it.

Where to look: Open the record > verify the MOP tab > then Logs tab.

MOPs are not configured (most common)​

Symptom: Posting fails — manually or silently from the cron — with an error listing one or more MOPs. Root cause: Validation auto-created a new MOP account for an unfamiliar payment method. New MOPs are created with Configured = False and block posting until reviewed. Recovery:

  1. Open each MOP listed in the error — see MOP Accounts.
  2. Set: posting mode (Detailed / Summarized), partner, sale journal, payment journal, accounts.
  3. Click Mark Configured.
  4. Return to the CVGo record and click Post (or wait one minute for the cron).

_check_company error​

Symptom: Posting fails with Some records are incompatible with company X or similar _check_company error. Root cause: A tax, journal, or partner referenced by the MOP belongs to a different branch than the CVGo record's branch. Multi-branch scoping is strict. Recovery: On the MOP account, verify sale_journal_id and payment_journal_id are scoped to the same company_id as the CVGo record. Re-check the "12% CVGo (Incl.)" tax exists for that branch — see Taxes. Then re-post.

Tax not applied to SO lines​

Symptom: Posting succeeds but invoices show wrong totals; no tax line on SOs. Root cause: No "12% CVGo (Incl.)" tax exists for that branch. Recovery: Run the multi-branch SQL sanity check in Troubleshooting. If the tax is missing, contact IT — it should have been seeded by the post-install hook.

Posting timeout​

Symptom: Posting hangs or times out, especially in Detailed mode. Root cause: Detailed mode creates 1 SO per transaction; high-volume days exceed the request budget. Recovery: The system processes 50 at a time per click/cron tick. Either wait — the cron will continue picking up where it left off — or click Post again. No data loss; no duplicates.

Posting failures​

If posting fails on click (not silently), the error appears in a popup. Match it against the table above. If it doesn't match anything documented, capture:

  • The full error text
  • The CVGo POS Data record ID
  • The branch
  • A screenshot of the Logs tab

…and escalate. Do not delete the record while a fix is pending.

Unbalanced reconciliation​

Symptom: After posting, the reconciliation tab shows Unbalanced or non-zero variance on one or more MOPs.

Distinguish the two flavors​

Variance sizeLikely causeRecovery
≤ 1.00 (any MOP)RoundingAcceptable; the system tolerates rounding under 1.00
> 1.00, single MOPManually edited / cancelled invoice or paymentAudit that MOP's invoices and payments; restore or correct
> 1.00, multiple MOPsSkipped transactions during postingSee Skipped transactions below
Whole-day mismatch vs. CVGoStation-side data issueEscalate to station before closing the day

Skipped transactions​

Symptom: The record shows Skipped transactions > 0. Some transactions are marked posted but no SO was created for them.

Where to look: Logs tab — error logs include the receipt identifier of the failing transaction.

Recovery:

  1. From the log, identify the failing receipt(s).
  2. Open the underlying transaction record. Check for: missing partner, invalid product, malformed amount, unknown tax code.
  3. Fix the data issue at the source if possible. For one-off failures, hand-create the matching SO + Invoice + Payment using the receipt number as the reference, then mark the transaction posted = True manually.
  4. Re-run reconciliation; variance should resolve.

If skipped transactions are recurring across multiple days, escalate — there's likely a code or config bug, not a data issue.

Already paid (non-issue)​

Symptom: Register Payments button is missing on an invoice. Root cause: All invoices on the record are already paid (typically because the auto-confirm + auto-pay flow ran during posting). Recovery: Nothing to do. This is the success case for auto-paid MOPs.

Escalate to IT when…​

  • A failure happens on more than one CVGo record from different branches on the same day
  • The same exception recurs after the documented fix
  • You see file-system, database, or _check_company errors that don't trace to a clear MOP/tax misconfig
  • Reconciliation is off by a whole-station amount with no skipped transactions
  • The cron jobs have stopped advancing records globally (check with another team — affects everyone)

Capture before escalating: record ID, branch, full error text, Logs screenshot, the source ZIP if available.

Recovery checklist​

  • Identified the state where the record is stuck
  • Read the Logs tab for the underlying error
  • Applied the documented recovery for that error
  • Re-ran the failing step (validate / post)
  • Confirmed the record advanced to the next state
  • Reconciliation variance is 0.00 (or within ±1.00 rounding)
  • No skipped transactions remain unaccounted for