💥 Common Issues

These are the most common problems users may face when installing or running the Ultimate Desktop app, along with suggested solutions.

💊 App Doesn’t Launch After Installation #

Possible Cause: The app is not linked to UltimatePOS properly or the client is not activated.

Solution:

• Make sure you have installed the Ultimate Desktop Connector module from the UltimatePOS module list.
• Go to the module and click Add Client, then create a client with a name like "Ultimate Desktop App" and assign the proper permissions.

💊 App Crashes Immediately After Opening #

Possible Cause: Incompatible Flutter version or missing dependencies.

Solution:

• Ensure you are using Flutter 3.32.4 (stable) or higher.
• Run flutter pub get to fetch all required dependencies.
• Run flutter doctor and make sure there are no critical issues.

💊 Database Read/Write Errors #

Possible Cause: Lack of file system permissions or local SQLite issues.

Solution:

• Try running the app as Administrator (Windows).
• Ensure the app has write access to local storage folders.
• Delete the existing database file in the AppData or equivalent directory and restart the app (a new one will be auto-generated).

💊 Missing JDK or Build Fails #

Possible Cause: JDK 17 is not installed or not configured properly.

Solution:

• Download and install JDK 17 from Oracle JDK Archives.
• Set the path using: bashCopyEditflutter config --jdk-dir="<path-to-your-jdk-17>"

💊 Data Not Displaying (Products, Users, Sales, etc.) #

Possible Cause: The app is not connected properly to the UltimatePOS backend or the local API is unreachable.

Solution:

• Make sure the UltimatePOS server is running on the same machine or within the local network.
• Check API configuration settings inside the UltimatePOS system.
• Try accessing http://localhost or the local IP from a browser to test API reachability.

💊 App is Lagging or Unresponsive #

Possible Cause: Insufficient system resources or heavy background tasks.

Solution:

• Ensure you are running on a machine with at least 8 GB RAM (16 GB recommended).
• Close unnecessary apps or processes.
• Use Release mode (flutter run --release) for better performance in production.