FAQ & Common Errors

Answers to the questions we hear most, plus step-by-step fixes for the errors that come up again and again during installation and setup.

Frequently asked questions

Installing

What are the server requirements?

PHP 8.2 or newer with the pdo_mysql, mbstring, fileinfo, openssl, curl, zip and gd/imagick extensions, MySQL 5.7+ (or MariaDB 10.3+), and Apache or Nginx with the document root pointing at the package's public/ folder. The web installer handles migrations, so no manual SQL import is needed. The full list, including the recommended cron entry, is on the Requirements & Stack page.

Do I need a Firebase project?

No. The website, the API and both mobile apps run perfectly without Firebase — it is only used for push notifications. The driver app's build even skips the Google Services plugin automatically when no google-services.json is present, so the project compiles out of the box. If you later want real pushes, follow the Firebase & Push guide.

Can I run the platform without push notifications?

Yes. Turn FCM off in Tools → Settings → FCM and the backend simply skips push delivery — the in-app notifications inbox in the mobile apps still records every notification, and email notifications still go out through SMTP. Nothing else changes. See Admin Tools for the toggles and Firebase & Push for enabling FCM later.

Will seeding the demo data overwrite my real data?

No. The demo seeder (MasterDemoSeeder) is written to be idempotent — it uses updateOrCreate for every demo account and record, so re-running it updates the existing demo rows and never touches your own customers, shipments or settings. You can seed it on a live installation and delete the demo records from the admin panel whenever you like. Details on the Demo Data page.

How do I update to a new release?

Back up first: copy your .env, the storage/ folder (uploads and logs) and dump the database. Then upload the new package files over the old ones — keep your .env and storage/ — and run php artisan migrate --force followed by php artisan config:clear and php artisan cache:clear. Rebuild the mobile apps only if the release notes mention app changes. The backup and upload steps are identical to the website installation flow.

Mobile apps

Can the user app and the driver app point at one backend?

Yes — that is the normal setup. Each app stores its own API base URL: the user app in cargoproapp/lib/constants/api_constants.dart (baseUrl) and the driver app in cargoprodriver/lib/core/api_config.dart. Point both at the same backend, e.g. https://your-domain.com/api. Walkthroughs are in Install the User App and Install the Driver App.

Which languages are supported, and how do I add one?

English, Arabic and Spanish ship with the product — the admin panel has JSON translation files in cargoproadmin/resources/lang/ and each app has .arb files under lib/l10n/. To add a language you copy the English files, translate the strings, and register the new locale on both sides; the step-by-step process is in Branding & Customization.

Is right-to-left (RTL) automatic?

Yes. The app's active locale is what drives layout direction, so the moment a user switches to Arabic the entire interface — navigation, lists, forms, input alignment — flips to RTL. There is no separate RTL switch to maintain; any other RTL language you add behaves the same way. See Branding & Customization for language settings.

Do I need a Mac to build the apps?

Only for iOS. Android APKs and app bundles build fine on Windows, Linux or macOS with Flutter 3.41+ and the Android SDK. iOS builds require a Mac with Xcode — Apple does not allow compiling iOS apps elsewhere. The toolchain list is on the Requirements & Stack page.

Notifications

Do pushes work on emulators and simulators?

Android emulators receive FCM pushes as long as the image includes Google Play services. iOS simulators do not receive FCM messages at all — test iOS push on a physical device with a valid push certificate or APNs key. Setup for both platforms is covered in Firebase & Push.

Why does the FCM test button say the service is not active?

The test in Tools → Settings → FCM refuses to send when the FCM toggle is off or the service account JSON is missing — that is the same check the backend applies before every push. Enable the toggle, paste the Firebase service account JSON from Project settings → Service accounts → Generate new private key, save, and test again. Full walkthrough: Firebase & Push and Admin Tools.

Billing & operations

How do I enable Stripe or PayPal?

In the admin panel go to Tools → Payment Gateways, open the Stripe or PayPal page, enable it and fill in the credentials — a secret key for Stripe, a client ID for PayPal. Save, and customers immediately see the option at checkout in the user app. Wire, cash and cash-on-delivery methods are configured from the same screen. Details and screenshots: Admin Tools.

Where do I change the tracking number prefixes?

Tools → Settings → Tracking & Invoice. The defaults are AWB for shipments, OS for online-shopping packages, CON for consolidates and LK for locker packages, and you can also set how many digits follow the prefix. Changes apply only to newly generated numbers; existing tracking numbers are never rewritten. See Admin Tools.

Common errors & fixes

The table lists every error we see regularly, with its usual cause and the fix. The five that need more explanation are expanded below it. Log lines quoted below come from storage/logs/laravel.log on the server or from flutter run / flutter build output on your machine.

Error / symptom	Cause	Fix
Android build fails: `Dependency ':flutter_local_notifications' requires core library desugaring to be enabled`	Gradle config lacks Java 8+ API desugaring (e.g. custom or old build files).	Already fixed in `cargoproapp/android/app/build.gradle.kts`. On a fresh clone: `flutter clean` then rebuild — see deep dive below.
App log: `PushNotificationService: Firebase not configured yet`	`firebase_options.dart` still contains the shipped placeholder values.	Run `flutterfire configure` for your Firebase project — Firebase & Push.
`laravel.log`: `FCM service is not active, skipping push`	FCM disabled or service account JSON empty in the backend settings.	Tools → Settings → FCM: enable the toggle and paste the Firebase service account JSON, then save.
`laravel.log`: `No FCM tokens found for user …`	The device never registered — the app was never logged in with notifications allowed.	Log into the app once with the notifications toggle on so it registers its token, then retest.
`laravel.log`: `No push template found …`	The `push_templates` table is empty (seeder not run).	Run `php artisan db:seed --class=PushTemplatesSeeder`.
White or blank page after installing the website	Document root not pointing at `public/`, or a required PHP extension missing.	Point the vhost at `public/` and verify extensions with `php -m` — deep dive below, Website install.
500 error right after installing	`storage/` / `bootstrap/cache/` not writable, or missing `.env`.	`chmod -R 775 storage bootstrap/cache` and restore a valid `.env` — deep dive below.
`419 Page Expired` or login loop in the admin panel	Stale cached config/routes/sessions from a previous host or install.	`php artisan config:clear` and `php artisan cache:clear` (add `route:clear view:clear` if needed).
App can't log in / `Connection refused`	Wrong or unreachable API base URL in the app.	Set `baseUrl` in `cargoproapp/lib/constants/api_constants.dart` (driver app: `cargoprodriver/lib/core/api_config.dart`) — User App install.
Emails not arriving	Missing or wrong SMTP credentials.	Check SMTP settings in `.env` / Tools, then `laravel.log` for mail errors; clear config cache after changes.
iOS push notifications not arriving	Testing on the iOS simulator.	Simulators cannot receive FCM — build to a physical device with APNs configured.
Google Play upload rejected (64-bit / icon issues)	Uploading a debug APK, or publishing under an application id you do not own. The shipped defaults are `com.devtrixx.cargouser` (user app) and `com.devtrixx.cargodriver` (driver app).	Build with `flutter build appbundle --release`. If you rebrand, change `applicationId` in each app's `android/app/build.gradle.kts` to an id you control — see Rename the application id / bundle id.

Android build fails: "flutter_local_notifications requires core library desugaring"

The exact error is Dependency ':flutter_local_notifications' requires core library desugaring to be enabled for ':app'. The notifications plugin needs Java 8+ API stubs on older Android versions, and Gradle refuses to build without desugaring. The fix is already shipped in cargoproapp/android/app/build.gradle.kts — it applies only to the user app, which is the one that depends on flutter_local_notifications:

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

If you see this on a fresh clone, you are almost certainly building with stale artifacts or a modified Gradle file. Run flutter clean, then flutter pub get, then build again. If you maintain your own build.gradle.kts, copy the two lines above into it — they are the only changes required.

App log: "PushNotificationService: Firebase not configured yet"

This is printed by the user app when the bundled firebase_options.dart still contains the placeholder values that ship with the project — Firebase is never initialized and push stays disabled. The app keeps working otherwise; only notifications are affected.

To fix it, install the FlutterFire CLI once, then run flutterfire configure inside cargoproapp/ and select your Firebase project and the app's platform entries. The command regenerates lib/firebase_options.dart with real values; rebuild the app and the message disappears. The full procedure, including the Android google-services.json step, is in Firebase & Push.

laravel.log: "No FCM tokens found for user …"

The backend wanted to send a push, found the user in the database, but had no device token for them — meaning no device ever registered for this account. A token is stored only after the app initializes Firebase, obtains the FCM token and posts it to the API, which happens right after a successful login with the notifications toggle allowed.

So the fix is simply: log into the user app once as that user, accept the notification permission prompt, and confirm in the app that notifications are enabled. Send a test push from Tools afterwards. If the line still appears, check the two related errors — the backend must have FCM active (next deep dives) and the app must not be printing the "Firebase not configured yet" message above.

White or blank page after installing the website

A completely white page means PHP executed but nothing rendered — almost always one of two things. First, the web server's document root must point at the public/ folder inside the package, not at the package root:

# Apache vhost
DocumentRoot /var/www/cargopro/public

# Nginx server block
root /var/www/cargopro/public;

Second, a required PHP extension may be missing. Compare the output of php -m against the requirement list — the usual culprits are mbstring, fileinfo and pdo_mysql. If the page is white but the browser console shows 404s for CSS, the document root is the problem; if php -v works but a trivial <?php echo 'x'; ?> file renders blank, it is the extensions. Both steps are part of the website installation and the server requirements.

500 error right after installing

A 500 on the very first page load is a server configuration issue, not an application bug. The two causes, in order of likelihood:

1. Permissions. Laravel must write to storage/ and bootstrap/cache/. From the package root run:

chmod -R 775 storage bootstrap/cache

On shared hosting do the same (775, or 755 with the web server as group) through the file manager. 2. Missing .env. If the installer never completed, .env may be absent or empty, so there is no APP_KEY. Restore the file from your backup or re-run the installer; php artisan key:generate creates the key if everything else is intact. After either fix, run php artisan config:clear once. See Website (Admin Panel) installation.

Still stuck?

We can look at it with you If none of the fixes above solves it, open a ticket at support.devtrixx.com or email support@devtrixx.com. Include the exact error text, the relevant laravel.log excerpt or build output, and the step you were on — it makes answers much faster. What to include and how to reach us is summarized on the Support page.

Previous ← Demo Data Next Credits & licenses →