17. Troubleshooting — When Something's Actually Broken

When the FAQ doesn't fix it, this guide does. We list the common breakage paths, what causes them, and the fix.

Before anything else: Force-close the app and reopen. Roughly 30% of "bugs" are stale UI state from poor connectivity. If that doesn't help, read on.

Login + auth

"Invalid phone number" on first login

Causes:

• Typo (extra space, country code mismatch)
• Account never created (you mistyped the number at sign-up)
• Number belongs to a different role (e.g., you registered as driver but try to log in as owner)

Fix:

1. Re-enter without spaces or +91.
2. Try with +91 prefix.
3. If that fails, contact admin — they can look up your record by name.

Wrong PIN 3 times → app locked for 5 min

Expected behavior. Wait it out:

• 3 wrong attempts: 5-min lock
• 6 wrong: 30-min lock
• 9 wrong: 24-hour lock

If you genuinely forgot:

• Tap Forgot PIN on the lock screen → admin (or your owner) resets it via SMS.

After login, app sends me back to phone-entry screen

Was a known bug. Fixed: wrong PIN no longer logs you out — just shows error and lets you retry. If you still see this, force-close and reinstall.

Logged out unexpectedly mid-day

Causes:

• Session expired (only happens at 30+ days idle — should be rare)
• Phone OS killed the app for memory; cookie cleared
• You logged in elsewhere with the same phone (only one active session)

Fix: log in again. Your data is safe; nothing was lost.

Data not appearing

Customer I added is missing

Check:

1. Did you save? Look for the "Saved" toast. If missed, the form was discarded.
2. Filter on customer list — Active only? Maybe you saved as Inactive.
3. Plan limit — did the save silently fail? Settings → My Plan → check if limit reached.
4. Refresh customer list (pull down).

Driver login shows empty checklist

Causes:

• No route assignment for that driver
• Today's shift doesn't match assignment (e.g., assigned only morning, it's evening)
• Today's day doesn't match (e.g., assigned Mon–Fri, it's Sunday)
• Subscription is_active = false
• Subscription's start date is in the future

Fix: open driver profile → Route Assignments → verify today's shift + day are covered. 12-drivers.md.

Today's deliveries didn't auto-generate

The system generates checklists nightly. If empty in the morning:

1. Hit the Generate button on the deliveries screen.
2. Check that subscriptions are active and frequency includes today's day.
3. Check start_date of subscriptions — future dates won't fire.
4. Last resort: contact support — there may be a backend cron issue.

Bill says ₹0 / didn't generate

Causes:

• No deliveries marked for that month
• All deliveries skipped
• Bill cycle hasn't ended yet (auto-generates only at month-end + 1)

Fix: Billing → manually generate by tapping the customer's row. If still ₹0, check the customer's khata for delivery records.

Payment + billing issues

Recorded payment but bill still shows unpaid

Force-refresh:

1. Pull down the billing list.
2. If still wrong, open the bill drawer — does it show the payment under "Payments" section?
3. If no payment row, the save didn't go through. Re-record.
4. If yes but status wrong: status updates can lag a second — wait 5s, refresh.

Customer paid via UPI but receipt didn't fire

Order of checks:

1. Owner toggle "Payment received" ON (Settings → WhatsApp).
2. Customer whatsapp_notify ON.
3. WhatsApp quota not exhausted.
4. Customer has valid WhatsApp number.

If all green but no receipt: contact support with bill # + payment ID.

Bill amount looks wrong

Common causes:

• A delivery was marked partial (charges only the partial qty)
• A subscription was paused for part of the month
• Customer has a custom price overriding default rate
• Payment was applied to the wrong bill (multi-month customers)

Open the bill PDF → it lists every delivery day-by-day. The math is transparent there.

WhatsApp issues

"Template doesn't exist" error

Means Meta hasn't approved the template under your business number. Contact support — only fixable on Meta side.

WhatsApp messages stopped firing today

Top suspects:

1. Quota exhausted — Settings → WhatsApp → usage card. Red bar = wait till 1st.
2. Owner toggle off — Settings → WhatsApp → check the relevant template's switch.
3. Customer opted out — whatsapp_notify OFF.
4. Wrong number / not on WhatsApp — message silently fails on Meta side.

Customer says they got an old message resent

WhatsApp / network can retry under poor connectivity. Real duplicates require the message to actually be re-fired — check your Send All history. If you didn't trigger, blame Meta's retry layer.

Counter mode issues

Counter customer count not updating after sale

Was a known bug — fixed via silent refresh. If you still see stale counts, force-close + reopen.

Counter sale won't let me edit

Was previously blocked when bills were paid / partial. Now removed — all counter sales are editable + cancellable. If you still see "This sale has a payment recorded — it cannot be edited", refresh app or update.

"Send WhatsApp update" toggle not visible on counter

Owner toggle "Counter / pickup update" must be ON in Settings → WhatsApp. If it's off, the per-sale switch hides.

Driver issues

Driver's app shows wrong dairy

Their phone is logged in to a stale session. Steps:

1. Driver: Settings → Sign out.
2. Re-login with their phone + PIN.
3. If still wrong, owner: check driver's owner_id in the driver record.

Driver can't mark partial / change qty

Plan or permission gating:

1. Driver record → "Can edit quantity" toggle (ON).
2. Plan tier — some plans block partial.

Driver swiped delivered on mobile but WhatsApp didn't fire

Was a known bug — fixed via keepalive: true + credentials: "include" on the fetch. If you still see it, force-close + reopen the app to load latest code.

App / device issues

App is stuck on splash / loading forever

1. Force-close (recent apps → swipe up).
2. Reopen.
3. Still stuck? Check internet (try opening a website).
4. Still stuck? Reinstall — uninstall then install from Play Store or milkgo.in.
5. Open ticket with support if reinstall doesn't fix.

App crashes when opening Reports

Reports load lots of data. Causes:

• Large date range on a slow phone
• Plan doesn't unlock historical reports → render error

Fix: pick "This month" first, see if it loads. Then try wider ranges.

"Network error" toasts repeatedly

Internet is patchy. The app retries automatically but if signal is too weak:

• Switch to mobile data (or vice versa)
• Move to better signal
• Mark deliveries; they'll queue and sync when network returns

Plan / billing issues

Paid for upgrade but plan still shows trial / expired

Wait 30 minutes — admin processes manually. If still stuck after that, send admin your payment screenshot via WhatsApp.

Plan expired but I'm sure I paid

Possible:

• Payment didn't reach (UPI failed / wrong UPI ID)
• Admin hasn't processed yet
• You renewed previous month's plan; the system extended from old end-date

Send admin: payment ref, amount, date.

"Plan limit reached" but I'm under the count

Refresh + retry. If still wrong, your plan record may not have synced — contact admin.

Still stuck?

When reporting:

• Describe what you did, what you expected, what happened.
• Include screenshots if possible.
• Mention your business name + phone so we can find your record.

We respond within 1 business day for emails; faster on WhatsApp / phone.

Related

• 16-faq.md — common questions
• 14-settings.md — profile, language, theme
• 15-plans-billing.md — plan limits + upgrade