Troubleshooting and FAQ
When a number looks wrong - freshness, known deltas, and who to ping.
Troubleshooting and FAQ
“Today’s numbers look different from Looker’s”
Expected. Today flows through the live path (20-second sync of order events); Looker read Aurora directly. Small intraday differences (an order mid-refund, a just-closed till) converge at the nightly sync. Compare closed days when checking parity - those come from the same upstream data Looker used.
“Yesterday’s number changed overnight”
The nightly sync re-covers a trailing 7-day window specifically to pick up late refunds and adjustments. A closed day’s totals can move slightly for up to a week; after that they are stable.
“The payout report didn’t arrive”
Payouts arrive on banking days. No email on weekends and bank holidays is the no-data suppression working, not a failure. Same for any report whose day genuinely had no rows.
“A scheduled email didn’t arrive on a weekday”
Check the send log on the admin page (https://data-plane.joe.coffee/v1/reports/admin): every subscription-period gets a row - sent, suppressed (no data), or failed with the error. Failures can be re-run safely (idempotent claims; no double-send).
“Metabase says too many connections / a dashboard is slow”
The reader role has a connection cap and dashboards fire all cards at once. Reload once; if a specific dashboard does it consistently, it has too many heavy cards - flag it and it gets split or optimized.
“The PDF report attachment failed”
The render service scales to zero when idle; the first render after a quiet period can time out and retry. If a scheduled PDF fails in the log, re-run it - if it fails twice, escalate.
Known deltas vs Looker (tracked, not bugs)
| Area | Delta | Status |
|---|---|---|
| Ladro daily sales IIF | Item-category income accounts (income:BEANS:, income:COFFEE: …) currently collapse into income:OTHER; totals are exact | Category-grain ingestion is the next data package |
| Ladro daily sales IIF | Fee lines lack Looker’s partial-refund corrections in some historical cases | Payout/fee-mirror package queued |
| Tips | Looker counted card tips only; platform may include cash tips | Adjudication open |
| Item margin | All rows missing cost | Cost ingestion not yet built |
| Labor / loyalty reports | Not yet migrated (no labor/loyalty data in the data plane) | On the migration backlog |
Escalation
Anything not covered here: ping David or drop it in the data channel with the report type, shop, date, and what you expected vs saw. Parity discrepancies against Looker get fixed same-day where the data exists.