This page is where you start when something in xMatix does not behave as you expect. It gives you the checks that settle most problems, explains how to read an error, and sends you to the page that covers the module you were working in.
Each module section of this Knowledge Center has its own troubleshooting page, written from that module's real refusals and error messages. Three pages in this section cover problems that cut across modules: access and sign-in, data and sync, and background work.
Overview
Most "something is wrong" reports fall into a few patterns. Once you know which pattern you are in, you know where to look:
- One user, not everyone. Missing apps, lists, records, fields or buttons that a colleague can see are almost always access settings doing their job. They are rarely a fault.
- Web against device. If the web and the mobile app disagree about a record, the cause is what the device has downloaded or still has queued. The server copy is usually fine.
- A record against a number. If a record looks right but a total, report or balance does not, the cause is in how the figure is computed or posted, not in the record.
- Nothing happened. If an import, a scheduled email, a sync or an overnight process seems to have done nothing, the answer is in a history screen, not on the record.
- A save or action was refused. If xMatix showed a message and stopped, the message names the rule that stopped it, and the module page explains that rule.
Procedure
Step 1 — Note what you see before you change anything
Write down the app, the list or record, and the time. On a list, note the saved view, the search text and any filters, because a filtered view or an old search can make records look missing when nothing is wrong. Copy the exact wording of any message. Do this first: clearing filters, retrying or editing the record can remove the evidence for a problem that only happens now and then.
Step 2 — Read the message
xMatix shows problems in a few standard ways:
- An error dialog has a short explanation, a Tracking Number with a copy button, a Details section with the full technical text, and a Retry button.
- A form that fails to save shows the reason on the form. It may add a line starting Ref: or Reference:.
- "Something went wrong on this page" means the page itself failed to display. The dialog offers Retry, Clear cache and Logout.
- "Unable to reach the server. Check your internet connection and try again." means your browser could not reach xMatix.
- On the mobile app, a change the server refused is listed under Pending changes with its reason and a Ref: code.
What each one means and what to try first is covered in Where to get help. Always copy the tracking number or Ref: code. It points to the exact request that failed.
Step 3 — Decide which pattern you are in
Use the patterns in the Overview, or the symptom table below, to choose a cross-cutting page or a module page.
Step 4 — Work through the page that owns the problem
Each module page lists its symptoms as the user would describe them, followed by the cause and the fix. Stop at the first cause that matches what you noted in Step 1.
Step 5 — Report what you found
If the page does not solve it, report it as described in Where to get help. Include what you did and what you expected, the exact app, list or record, when it happened, the exact message, and the tracking number or Ref: code. A report that lets someone retrace your steps gets fixed much faster.
Find the page for your symptom
| What you see | Start here |
|---|---|
| A user can't sign in | Access and sign-in |
| A user is missing an app, list, record, field or button that colleagues have | Troubleshooting: a user can't see something |
| A record is on the web but not on a phone, or the other way round | Data and sync |
| Records seem to have disappeared from a list | Data and sync |
| An import, scheduled job or overnight process did nothing or failed | Background work |
| A scheduled email never arrived, or came at the wrong hour | Troubleshooting analytics |
| A save is refused by a rule your organization set up | Entity behavior and Business rules |
| A business rule never fires, or overwrites a value | Business rules |
| An approval is stuck or went to the wrong person | Approvals |
| A new record has no number, or the wrong number | Document numbering |
| A document did not post to the general ledger | Posting Error Log |
| Posting is refused because the period is closed | Fiscal periods and period close |
| A record differs from the system it syncs with | Troubleshooting integrations |
| The Sense assistant is missing or stops answering | xMatix Sense |
The module troubleshooting pages
| Module | Start here | Typical territory |
|---|---|---|
| Analytics | Troubleshooting analytics | Missing or empty reports, blank dashboards, subscription emails that never arrive or arrive at the wrong hour |
| CRM | Troubleshooting CRM | Conversion refusals, generation actions that won't run twice, empty configurators, full appointment slots |
| Data Studio | Troubleshooting Data Studio | Stale datasets, missing rows, failing compiles and builds |
| Developer surface | Troubleshooting the developer surface | Command-line sign-in and workspace errors, push rejections, API 401/403/404 responses, version drift |
| Expenses | Troubleshooting Expense Management | Claims that won't submit, approved claims that never posted, posting errors, refused reimbursements, balances that don't tie |
| Field service | Troubleshooting field service | Work that doesn't route, resources not offered for a slot, an empty dispatch map |
| Finance | Posting Error Log and Fiscal periods and period close | Documents that did not post, closed or locked periods, period balances that look wrong |
| Integrations | Troubleshooting integrations | Schedules that never fire, tests that pass while runs fail, conflict backlogs, records that stop syncing |
| Inventory | Troubleshooting inventory | Stock or valuation that looks wrong, unposted or in-transit stock, closed periods |
| Mobile app | Troubleshooting the mobile app | Records missing on the device, changes not syncing, sign-in, stale data and layouts, storage warnings |
| Payroll | Troubleshooting payroll | Refused setup saves, employees missing from a run, zero TDS, failed posting, payment batch errors, challans |
| Portals | Troubleshooting portals | Not-found responses, missing or empty pages, data lists with no rows, signup that does nothing |
| Procurement | Troubleshooting procurement | Releases that refuse to run, receipts that won't receive or post, bills that don't move the order, auto-order suggestions that look wrong |
| Rewards | Troubleshooting rewards | Compensation lines with no reward, unexpected amounts, wrong achieved figures |
| Sales | Troubleshooting sales | Orders that won't allocate, prices that look wrong, schemes that didn't apply, credit-limit blocks |
| Sense AI | xMatix Sense and Setup Copilot | A missing assistant button, an assistant that stops answering, no nudges, a change that was described but not made |
| Service | Troubleshooting service operations | Nothing pending to process, contract validation failures, blocked completion |
| Support desk | Troubleshooting the support desk | Cases that won't route, SLA clocks that surprise you |
| Tax Center | Troubleshooting the Tax Center | GST figures or returns that are missing or wrong, e-invoices, e-way bills, TDS challans and returns |
| Telephony | Troubleshooting telephony | A missing softphone, calls that don't ring, unmatched callers, absent recordings |
| Warehouse | Troubleshooting warehouse operations | Fulfilment ordering rules, delivery and shipment errors, cycle count locks |
Two sections are routed differently. Commerce questions are answered in the Commerce FAQ. Field sales work, such as visits, routes and van sales, is done in the mobile app, so its symptoms are covered by the mobile troubleshooting page. Order and pricing questions from the field go to sales.
The cross-cutting pages in this section
- Access and sign-in: a user can't sign in, or is signed in but something is missing.
- Data and sync: data looks wrong or missing, on the web or on a device.
- Background work: jobs, sync runs, subscriptions and messages, where to see them and how to read their failures.
Common problems
A button that a colleague has is missing for me
Whether you see New, Edit and Delete depends on what your security profiles allow you to do with that kind of record, and on whether the record type allows the action at all. Other buttons, such as custom actions, print and preview, need their own grant on your profile. Your administrator can compare your access with your colleague's on the Access Diagnostics tab of your user (Setup → Access Control → Users). The full walk is in Troubleshooting: a user can't see something.
A save is refused with a message I don't recognise
Your organization can add its own validations and business rules, so the message may not come from xMatix itself. Every validation whose condition is met rejects the save, whatever severity it was given. Copy the message and the Ref: line and send them to your administrator. They can find the rule under the record type's behavior settings, as described in Entity behavior.
The page shows "Something went wrong on this page"
Select Retry first. If the same page fails again, select Clear cache, which removes the screen definitions your browser has stored, and then Retry. If it still fails, report it with the tracking number from Details. See Where to get help.
A scheduled job ran at the wrong hour
The time you enter for a job schedule on the Jobs screen is in UTC, not your local time. Convert your local time to UTC before you save the schedule. See Background work.
Training
Practice exercise
In a sandbox, sign in as a test user who does not have access to one record type, for example a user with a narrow security profile. Try to open that record type from the App Launcher, and note what you see. Then, as an administrator, open that user's Access Diagnostics tab and find which profile or license explains it.
Expected result: you can name the missing access from the diagnostics, without changing anything, and you know that Troubleshooting: a user can't see something is the page for this pattern.
Quick reference
- Note the app, list, view, filters and time before you change anything.
- Copy the exact message and its Tracking Number or Ref: code.
- One user missing something: check access first.
- Web and phone disagree: check the device's offline data and pending changes.
- Something "never happened": check the Jobs screen or the module's history screen.
- A refused save names the rule that refused it; the module page explains the rule.
- Job schedule times are UTC.
- Report what, where and when, with the reference code.
Common questions
Where do I find the tracking number?
In an error dialog, the Tracking Number sits under the explanation with a copy button next to it. On a form that failed to save, look for a line starting Ref: or Reference:. On the mobile app, a refused change shows a Ref: code under its reason on Pending changes. The code identifies the single request that failed, so whoever investigates can find the exact failure without guessing the time or the record. Copy it rather than retyping it, because one wrong character makes it useless.
Is something wrong with my data if a list looks empty?
Usually not. A list shows only the records that match its saved view, your search text and any filters, and only the records your access lets you see. Before you assume records were lost, switch to another view, clear the search and filters, and ask a colleague with wider access to look at the same list. If the records are still missing, follow Data and sync, which also covers deleted and imported records.
Should I retry an action that failed?
For an error caused by a lost connection, yes. But first open the record again and check whether your change was saved, so you don't apply it twice. For a refusal that names a rule, retrying gives the same result until the cause is fixed, so read the module page first. For a background job, the Jobs screen has its own Retry, which starts a new run. See Background work.