Mobile not syncing / push not arriving#

Two related complaints: the app shows stale data (or a stuck sync queue), and notifications never arrive on the phone. Both have clear diagnostics on the device itself — the Sync queue page and the Device Health screen — plus a server-side test push. Work in that order; almost every case is solved on the phone or in the workspace's app settings, not by changing code.

Who this is for: agents with a misbehaving app, and admins/super admins supporting them.

Problem#

• Data in the app is old; actions taken offline stay "waiting"; the number "N waiting · N retrying" will not go down.
• Push notifications (new lead, assignment) never appear — even though the lead exists in the CRM.

What you see#

Likely causes#

• Device token gone: tokens last up to 90 days; they are revoked on logout or expiry. An old session gets 401 UNAUTHORIZED on every call — the app looks "not syncing" when it is actually signed out server-side.
• No network / flaky network: items queue up correctly and will flush; a very long queue just needs connectivity and time.
• Redelivery backoff: failed uploads retry with exponential backoff — a "retrying" count is not failure, but a growing one is.
• Push not wired: the workspace must connect its own Firebase project (BYO-Firebase — there is no bundled google-services.json; the app initialises Firebase at runtime). Not configured = no push, cleanly reported as such.
• Notification permission (Android 13+) missing, or notifications disabled for the app channel (leadhub_default).
• Battery optimisation restricting the app in the background — sync and push handling both suffer.
• Wrong server address — the app talks to the wrong install entirely; the URL must end with /.
• Maintenance mode — the platform may be showing a maintenance message and pausing normal flow.

Quick fix#

1. More → Device health: fix anything that is not "Registered" — above all the Push notifications (FCM) row.
2. On the Sync queue page press Sync now; if items remain stuck, press Retry failed and watch the counts for a minute.
3. If the app keeps erroring back to login, sign out and sign in again — this issues a fresh 90-day token.
4. Ask the super admin to send a test push: php artisan leadhub:test-push {email}.

Step-by-step fix#

1. Read Device Health first. Rows show Registered / Permission denied / Not configured / Pending. What each means:
   • Registered — this capability is working.
   • Permission denied — the OS-level permission is missing; grant it (including notification permission on Android 13+).
   • Not configured — the capability needs workspace/platform configuration (typically FCM) — the super admin must connect Firebase.
   • Pending — registration is in progress or waiting on first network contact; retry after a moment.
2. Check the server address. Login screen → the Server: line. It must be your install and end with /. A wrong address explains "nothing works on this phone" completely.
3. Work the sync queue. "N waiting · N retrying" — use Sync now; use Retry failed for stuck items. Note that uploads are idempotent, so retrying never duplicates calls or notes. Persistent retrying on one item is a data problem — capture what the item is and escalate.
4. Battery. Set battery usage to Allow unrestricted for the app. On aggressive OEMs, also enable autostart/background activity.
5. Unblock notifications. Android Settings → Apps → the app → Notifications: enabled, and the channel leadhub_default not muted. Check Do Not Disturb is not swallowing them.
6. FCM configuration (server side). Push uses the workspace's own Firebase project — connected Firebase details (the same project as Firebase phone OTP if you use it). If Device Health says Not configured, no amount of phone-side fixing will help until Firebase is connected in the CRM.
7. Test push. php artisan leadhub:test-push {email} sends to that user's registered devices. If the test arrives, push plumbing works and the issue is the specific notification; if it does not, check the Device Health FCM row again and the Firebase project.
8. Maintenance mode. If the app shows a maintenance message, check Super Admin → Settings → Mobile App Login (/super-admin/settings/mobile-app-login) — the maintenance message and flags live there (workspaces can override on their own mobile login settings page). Turn it off to restore service.

Admin fix#

• Walk the agent through Device Health and the sync queue by screen-sharing or a photo of the screen — the rows name the exact problem.
• New-device registrations appear under Super Admin → Android App → Devices; if an agent has signed in from several phones, old entries explain duplicate/confusing notification behavior.
• Workspace-level mobile settings: Admin → Mobile login settings (/admin/mobile-login-settings-page) — enable/disable login methods and set workspace-level maintenance messaging.

Developer fix#

• API auth: DeviceAuthenticate resolves the bearer token against device_tokens.token_hash; failures return 401 with {"error":{"message":"…","code":"UNAUTHORIZED"}}. A suspended user gets "This user account is not active." — the app is not broken; the account is blocked.
• Tokens: valid up to 90 days; revoked on logout or expiry — not revoked by a password change. Force a fresh token by signing out/in (or revoke the device server-side).
• Offline queue: Room-backed, uploaded via WorkManager with backoff; uploads are idempotent.
• Push: runtime Firebase initialisation (no bundled google-services.json); default channel leadhub_default. Server config comes from the platform + tenant mobile app settings; MobileAppConfig carries the maintenance: {active, message} payload the app displays.
• Deep links (crm://lead/{id}, and equivalents) open the right record from a notification — if a tap opens the wrong screen, that is a deep-link bug to report with the notification payload.

Logs to check#

• Device Health rows on the phone (FCM, permissions, battery) — always the first source.
• Server: storage/logs/laravel.log around the user's sync attempts; 401s there confirm a token problem.
• php artisan leadhub:test-push {email} output — confirms whether the server considers the device pushable.
• Failed jobs (php artisan queue:failed) if notifications are queued but not leaving the server.

When to escalate#

• Device Health shows Registered for FCM and test pushes send, but nothing arrives on any device — that is a Firebase/hosting configuration issue for the super admin.
• A single sync item retries forever with valid connectivity — a developer should capture the item's payload before it is cleaned up.
• Multiple agents report the same behavior at the same time — treat it as a service incident, see Incident response.

Related guides#

• Cannot log in
• Calls & recording issues
• Offline sync
• How push notifications work