Use this page when the xMatix mobile app does not do what you expect: a record is missing, a change will not upload, sign-in fails, a screen says it needs a connection, or a form still looks old. Most of these problems fall into one of three cases. The data was never kept on the phone, a queued change is waiting for you, or the screen needs the server right now. The app tells you which case you are in, so start by reading what it says, before you change anything.
Overview
The app reports its state in four places. Check them before anything else:
- The line above the tab bar. Offline, it reads Offline · 3 changes waiting, or Offline · changes sync when you're back when nothing is queued. When a change needs you, it reads, for example, 2 changes need attention. Tap it to go to the right screen.
- Sync Status (Apps → Preferences → Sync status). The Changes row summarises your queue, for example All changes synced or 4 need attention · 1 waiting. The Offline data card has one row for each record type kept on the phone.
- Pending changes (tap Changes on Sync Status). It lists every queued change under Needs attention and Waiting to sync, with what to do about each.
- Diagnostics (Apps → Preferences → Diagnostics). It shows the app Version and has Share diagnostics for sending details to your administrator.
The model behind all of this is explained in How offline-first mobile works. Step-by-step help for the Sync Status and Pending changes screens is in Working offline.
How xMatix handles it
- Permissions are the same on the phone and the web. If a record opens on the web, your access is not why it is missing on the phone.
- Only some data is kept on the phone. Your administrator chooses which record types are kept offline. Reference data such as accounts and items is kept in full. Transactions such as orders are kept for a recent window, 90 days as shipped. A record type with more rows for you than the row cap stays online only.
- While you are connected, screens ask the server (the default Online first read mode). So a record that is missing while you are online is not caused by offline settings. Check views, search and filters first.
- Your changes wait in a queue on the phone. They upload in the order you made them. Only Discard on a change, Delete all offline data, or an administrator settling a failed change from the server as Resolved or Won't Fix removes them. Signing out, an expired session, restarting the phone and Reset offline data all keep them.
- Failures that cannot recover are reported. When a change ends as Rejected or Conflict, the app also files a Mobile Sync Failure record for your administrator (Monitoring sync failures).
Prerequisites
- The mobile app installed and signed in, with your first download finished. See Using xMatix on mobile.
- For the administrator steps: access to Setup → Design Studio → Apps → Mobile Apps in the web app.
Common problems
A record shows on the web but not on the phone
- Check the list itself. Make sure you are in the right app and view, then clear any search text and filters. Mobile lists have no "All" view; the view selector shows only the views your app offers. See How the mobile app is organized.
- If you are online, pull down to refresh the list. Screens read from the server while you are connected, so a record created on the web a moment ago appears after a refresh.
- If you are offline, open Sync status and find the record type on the Offline data card:
- No row for the record type means it is not kept on your phone. You can open it only while connected.
- Off means the record type is not downloaded.
- Manual means automatic syncs skip it. It downloads on demand, for example when you tap its Manual pill (the pills show only when your administrator lets you choose).
- Online only · … — more than this device keeps offline means you can see more rows than the row cap, so the record type is not downloaded for you.
- … records on device (last N days) means older transactions are not kept. A record last updated before the window is not on the phone.
- If the row is red, the last download of that record type failed. Tap the row to read the error, which opens a … sync failed panel named after the record type. Then tap Sync now.
If your team needs a record type offline every day, ask your administrator. They can add it to the app's offline list or widen its window (Configuring the mobile app).
My changes haven't reached the server
Open Sync status and tap Changes to open Pending changes.
- Waiting to sync rows are Pending, Syncing…, Retrying or Waiting — document is being processed. They upload by themselves once you have a connection and the app is open. Tap Sync changes at the top to send them now.
- Needs attention rows will not upload until you act:
- Rejected (Rejected by the server, or the server's own message). Tap Fix to correct the values in the form and save again, or tap Discard. A change that fails five times in a row for network or server reasons also ends up here.
- Conflict (Changed on the server since your edit). Someone changed the same field on the server. Tap Keep mine to write your value over theirs, or Discard.
- Blocked (Waiting on a related change that failed). Fix or retry the change it depends on, such as the order a line belongs to. The blocked change then goes on its own. If you discard that change instead, discard the blocked ones too, because they stay blocked.
When an upload pass ends with failures, the app also tells you, for example 2 changes could not upload. Open Preferences › Sync status › Pending changes to fix them. When the queue empties, you see All changes uploaded.
When you report a failed change, include the Ref: code shown under the error. Your administrator can use it to find the same failure in the server logs.
I tapped "Retry all" and the conflict came back
Retry all sends every Needs attention row again as it was. A Conflict row sent again can conflict again. Open the row and tap Keep mine instead, or Discard it and redo your edit on the current version.
I can't sign in
- Offline, with an existing session. Starting the app with no connection keeps you signed in, and you can work with the data on the phone.
- A fresh sign-in needs a connection, after you have signed out or on a new phone, because the server checks who you are. If you sign out without coverage, you cannot get back in until you have a connection. Your queued changes stay on the phone and upload after you sign in again on the same phone.
- Online and still failing. Try the same email and password on the web. If the web also fails, the problem is with your account, not the app, so contact your administrator. Incorrect email or password. means the password is wrong. The app has no forgot-password link, so reset your password from the web sign-in page. More sign-in messages are in Using xMatix on mobile.
The app sent me back to the sign-in screen
Your session ended and could not be renewed, or you saw Your session has expired. Sign in again to continue. Nothing in your queue is lost. Sign in again with the same account, organization and app on this phone, and the queue starts uploading again. Queued changes do not follow you to a different phone.
A tab or screen shows a crossed-out cloud or says "Not available offline"
That part of the app needs the server right now. While you are offline, tabs and More items whose data is not on the phone show a crossed-out cloud icon, including Reports and Dashboards. Inside a screen, the same thing shows as Not available offline. This happens on report viewers, the attachments section, the approval panel, lookup pickers, Sense chat data cards, and lists or related lists whose record type is not kept offline. Nothing is broken. Reconnect and the screen works again.
"This record can't be saved offline. Reconnect to save."
You are offline, and this record type cannot be saved offline. Inline edits and grids show You're offline. This record can only be saved with a connection. instead. Either the record type is not on your app's offline list, Editable offline is turned off for it, or Offline caching is switched off on your phone (Preferences → Data & Sync). Save once you are connected. If the team needs it offline, ask your administrator.
"This action requires a connection"
Buttons that run an action on the server (approve, post, convert and similar) never run offline. Your saved field changes are not affected. Reconnect and run the action again. Some screens word this their own way, for example Booking an appointment requires a connection. or E-way bills are not available offline.
A form, field or label still looks old after the administrator changed it
- Make sure you are online and tap Sync now on Sync status. Each sync checks for newer forms, fields and translations.
- If it is still old, open Apps → Preferences and under Data & Sync tap Refresh Metadata. Confirm the prompt. The app clears its cached forms, fields, translations and the app definition (branding and offline settings), downloads them again and starts a sync. Your offline data and pending changes are not affected.
The app list or branding didn't change after the administrator published
The list of mobile apps you can use is fetched when you sign in or switch organization, and when you pull down to refresh on Choose an app. It is not fetched again when you bring the app back to the foreground. Use Refresh Metadata to pick up a changed app definition, or switch organization and back from Profile.
The app says storage is almost full
When the phone has less than 500 MB free, the app shows Storage almost full — offline sync is disabled until space is freed. The Offline data card reads Offline sync is disabled — storage almost full. Downloads stop, but your queued changes keep uploading, and Sync now on Sync Status becomes Sync changes. The app checks free space when it starts and whenever you return to it. To fix it:
- Free up space on the phone outside the app, then return to the app.
- Open Preferences → Storage & database and tap Optimize database. It reports Reclaimed …, or Database is already compact. The By entity list shows which record types use the most space.
- If your administrator allows it, set record types you don't need to Manual or Off with the pills on the Offline data card. Turning one off asks Stop offline sync? and keeps your unsent changes. Reset to app defaults undoes your choices.
On a phone with little memory, you may instead see Low-resource device — background sync limited to essential data. That message is about the phone's memory, not storage, and needs no action.
Downloads keep failing, or the offline data looks wrong
Open the red row on the Offline data card to read the error, and tap Sync now. If the data on the phone disagrees with the web in a way a sync does not fix, tap Reset offline data under Maintenance on Sync Status. It downloads the offline data again from the server and keeps your pending changes. Do not use Delete all offline data on the Storage & database screen for this, because it also deletes changes that have not uploaded.
A photo or file I added is missing on the server
How the file was captured decides what happened to it:
- Photos and signatures taken in visit tasks are queued, offline too. Look for a File upload · … row on Pending changes.
- Files picked on a new record are held until you save and then queued with the record. If one could not be queued, the app says Saved, but … could not be attached. Add it from the record.
- Files added to a record that is already saved upload straight away and are not queued. Offline, the attachments section shows Not available offline. If an upload fails, you see Upload failed. Add the file again while you are connected.
My location trail has gaps after I signed out
Signing out stops location tracking and drops any positions that had not uploaded yet. They never appear on Sync status or Pending changes. See Location tracking on mobile.
Example
A field representative visits three outlets in an area with poor coverage. At the second outlet they create an order and attach a photo of the shelf from the visit task. The line above the tab bar reads Offline · 2 changes waiting.
Back in coverage, the photo uploads but the order does not. The line now reads 1 change needs attention. They tap it, and Pending changes shows Create · Order under Needs attention, Rejected, with the message that a required field is empty and a Ref: code. They tap Fix, fill in the field and save. The row moves to Waiting to sync, uploads, and they see All changes uploaded. The rep's administrator also sees the earlier rejection as a Mobile Sync Failure and marks it resolved.
Training
Practice exercise
On a sandbox phone whose app keeps Order offline:
- Turn on flight mode and check that the line above the tab bar reads Offline · changes sync when you're back.
- Open Reports from the tab bar or More and note the crossed-out cloud icon or Not available offline.
- Create an order and save it. Confirm that you see Saved offline — will sync when online.
- Open Apps → Preferences → Sync status, tap Changes, and find the Create · Order row under Waiting to sync.
- Turn flight mode off and tap Sync changes.
Expected result: the row disappears, Changes reads All changes synced, and the order opens on the web.
Quick reference
- Line above the tab bar: offline, waiting count, or changes needing attention. Tap it.
- Preferences → Sync status → Changes opens Pending changes: Fix, Retry or Keep mine, and Discard.
- Missing record online: clear the view, search and filters, then pull to refresh. Offline: check its row on Offline data.
- Crossed-out cloud or Not available offline: reconnect.
- Old form: Sync now, then Preferences → Refresh Metadata.
- Storage below 500 MB: downloads stop, uploads continue. Use Optimize database.
- Bad offline data: Reset offline data (keeps changes), never Delete all offline data.
- When reporting: the Ref: code and the app Version from Diagnostics.
Permissions
The phone uses your web account and security profile. Anything you are not allowed to do on the web is refused when the change uploads, and shows as Rejected. Every user can open Sync Status, Pending changes, Storage & database and Diagnostics. Choosing Auto, Manual or Off for a record type is possible only where the administrator has turned on User override for it. Mobile Sync Failure records are for administrators. Who can see them is set up as described in Monitoring sync failures.
Configuration
Most fixes on this page that need an administrator are settings on the mobile app configuration (Setup → Design Studio → Apps → Mobile Apps, open the configuration). See Configuring the mobile app.
| User's symptom | Setting to check |
|---|---|
| A record type has no row on Offline data | Add it on the Offline & Sync tab |
| A record type is Online only | Max rows for the type, or Default max offline rows; its Scope |
| Older transactions are missing offline | Window (days) for the type, or Default transaction window (days) |
| "This record can't be saved offline" | Editable offline for the type |
| Users want to switch a type off on their phone | User override for the type |
| Some users get a narrower offline set | Profile overrides (the most restrictive wins) |
| A user sees no mobile app setup at all | The Profiles tab and whether the configuration is active |
| Changes keep coming back Rejected | The validation rule or permission named in the error; Mobile Sync Failure records list them |
After you change a configuration, ask the user to tap Refresh Metadata to pick it up straight away.
Common questions
What should I send my administrator when something fails?
Send three things. First, what Sync status shows: the Changes summary and any red row on Offline data. Second, the Ref: code of each failed change on Pending changes. Third, the app Version from Preferences → Diagnostics, where Share diagnostics sends the details in one go. Leave customer names and other personal data out of screenshots. Rejected and conflicted changes also reach your administrator as Mobile Sync Failure records, so with the Ref: code they can usually find the cause quickly.
Will signing out fix sync problems?
No, and it can make things harder. Signing out keeps your queued changes on the phone, but they upload only after you sign in again on the same phone, and signing in needs a connection. With changes waiting, the Profile screen warns Uploads still waiting. Tap Stay signed in, get a connection and wait for All changes synced. To fix a stuck change, use Fix, Retry or Discard on Pending changes. To repair bad offline data, use Reset offline data, which also keeps your changes.
Does reinstalling the app help?
Avoid it while changes are waiting. Uninstalling removes the app's storage on the phone, including changes that have not uploaded. Try Sync now, Refresh Metadata and Reset offline data first, because none of them touch your pending changes. If you reinstall anyway, first check that Changes reads All changes synced.