Offline, sync and troubleshooting

This guide explains safe offline operation, pending work, synchronization, and recovery from common application errors.

What offline mode means¶

QuickTill can preserve some supported operations on the device when the server is temporarily unavailable. Those records must later synchronize with the server.

Not every operation can run offline. Provider payments, subscription checks, some administrative changes, and server-confirmed fiscal actions may require connectivity.

Recognise status¶

• Online: the server is reachable.
• Offline: requests cannot currently reach the server.
• Pending: local work is queued for synchronization.
• Syncing: QuickTill is currently sending or refreshing data.
• Failed: the server rejected an item or repeated attempts did not complete.

Safe offline workflow¶

1. Confirm the app explicitly allows the operation to continue offline.
2. Complete the operation once.
3. Record or retain its local reference.
4. Do not clear browser storage, app data, or device storage.
5. Restore a stable connection.
6. Select Sync now.
7. Review pending and failed records.
8. Confirm the count returns to zero.

Pending and failed sales¶

From POS, open More actions > Pending and failed sales.

• Review the local order reference and timestamp.
• Read the current state and recorded error.
• Confirm whether the same sale already exists in receipts.
• Retry only when it is not already accepted.
• Escalate repeated validation or server errors.

Never create a second sale until the first sale's status is known.

Pending inventory work¶

Product, GRV, transfer, and other inventory screens can have their own pending or offline lists.

1. Open the relevant pending list.
2. Identify the operation type and local reference.
3. Restore connectivity.
4. Select the screen's Sync action.
5. Resolve missing product, inventory, supplier, permission, or duplicate validation errors.

Refresh versus sync¶

• Refresh downloads current data from the server.
• Sync sends locally pending changes, then may refresh data.

Do not repeatedly start refresh while a sync is active. Allow the existing operation to finish.

Large product catalogues¶

For a catalogue containing thousands of products:

• Load one moderate page at a time.
• Search on the server by product name, SKU, or barcode.
• Cancel or ignore stale search responses when the query changes.
• Do not request every page in parallel; too much concurrency can overload the API, browser memory, and device.
• Display only visible rows using pagination or lazy lists.
• Cache essential POS fields rather than full back-office records.
• Avoid loading the complete product catalogue on Dashboard or unrelated screens.

If loading never ends after the final page, capture the last requested page and displayed total. This normally indicates completion state was not cleared, not that another page is required.

When a screen keeps loading¶

1. Wait for the current request to finish once.
2. Check the connection indicator.
3. Narrow the date range or search.
4. Return to the previous screen and reopen it.
5. Use one refresh action.
6. Record the failed API request or error message if it continues.

Avoid opening the same data-heavy screen in multiple tabs.

Red error screen in development¶

A red Flutter error page indicates an application exception or assertion.

Capture:

• The full first error message.
• The route or screen.
• The exact action immediately before it.
• The console stack trace.
• Whether it occurs in debug only or also in a release build.

An assertion such as _dependents.isEmpty often points to navigation or inherited-widget lifecycle handling. It should be fixed in code rather than hidden from the user.

HTML error displayed as a page¶

If a device displays raw HTML containing NotSupportedError, the app opened an API error response as if it were normal content.

1. Record the endpoint and action.
2. Return to QuickTill.
3. Confirm connectivity and authentication.
4. Do not repeatedly submit the operation.
5. Check whether the operation is supported by the deployed backend.
6. Escalate the response status and reference to support.

Standard recovery sequence¶

Use these steps in order:

1. Preserve pending data and references.
2. Confirm the server and internet are reachable.
3. Select Sync now once.
4. Refresh the affected screen.
5. Sign out and sign in only if no unsaved form work will be lost.
6. Restart the application.
7. Restart the device if the operating system or Bluetooth is unresponsive.
8. Contact support with diagnostics.

Do not uninstall, clear storage, or reset the database unless support confirms pending work is safely backed up.

Information for support¶

Provide:

• Tenant and branch name.
• User name, but never the password.
• Device platform and QuickTill version.
• Date, time, and timezone.
• Screen and action.
• Order, receipt, transfer, GRV, or local reference.
• Exact error text.
• Whether the issue is repeatable.
• Privacy-safe diagnostics from Support & Diagnostics.

Recovery checklist¶

• [ ] Pending references were preserved.
• [ ] Duplicate submission was avoided.
• [ ] Connectivity was verified.
• [ ] Sync was attempted once and observed.
• [ ] Server receipts were checked.
• [ ] Exact error and timestamp were captured.
• [ ] App storage was not cleared.
• [ ] Support diagnostics exclude secrets.