Help

Troubleshooting & FAQ

Website & server

500 / blank error page

Three usual causes, in order: (1) no .env file — the package ships only .env.example; run cp .env.example .env. (2) .env exists but isn't writable — the app writes its own APP_KEY on the first request, which silently fails on a read-only file; chmod 664 .env or run php artisan key:generate yourself. (3) storage/ + bootstrap/cache/ permissions. Temporarily set APP_DEBUG=true to read the exact error (turn it back off after).

Plain "Server Error" (500) on / or /admin right after a successful install

In production APP_DEBUG is false, so the browser shows a bare error page and never names the cause. Read the log first — do not guess:

tail -50 storage/logs/laravel.log

Match what you find there:
• Vite manifest not found — the frontend was never built. The wizard does not need it, which is why this only appears once the wizard hands you over to the real site. Run npm ci && npm run build (Node 20.19+), or build on your own computer and upload public/build/.
• Failed to open stream: vendor/autoload.php — Composer never ran.
• Undefined variable or any other PHP error — a different fault entirely; find its own entry on this page rather than rebuilding assets.

"Failed to open stream: vendor/autoload.php"

PHP dependencies were never installed — the package ships without vendor/. Run composer install --no-dev --optimize-autoloader in the app folder, or run it locally and upload the resulting vendor/ directory.

Host has no SSH / Composer / Node

Run the build on your own computer: composer install --no-dev, cp .env.example .env, npm ci && npm run build — then upload the whole folder including vendor/, public/build/ and .env. The result is identical to building on the server.

Images don't display

Run php artisan storage:link and confirm APP_URL is your real domain. See Media Storage.

Old settings keep showing

Clear caches: php artisan config:clear && php artisan cache:clear, then re-cache.

"419 Page Expired" on login

Session/cookie issue — check APP_URL, HTTPS and that the system clock is correct.

Database connection error

Re-check the DB_* values in .env against the database you gave the install wizard.

Notifications/emails never send

The queue worker isn't running. Start it (Supervisor or cron fallback).

License won't activate

Server must allow outbound HTTPS; verify the purchase code has no stray spaces. See License Activation.

composer install: "requires php ^8.3 but your php version (8.2.x) does not satisfy that requirement"

Your shell PHP is older than the one your website uses. On most shared hosts these are two separate binaries, so changing the PHP version in the hosting panel does not change what php means over SSH.

php -v                                    # what the shell uses right now
ls /usr/bin/php8* /opt/alt/php8*/usr/bin/php 2>/dev/null   # what is installed

Then put a supported binary first on your PATH for the rest of the session:

# CloudLinux / Hostinger layout — adjust to match your ls output
export PATH=/opt/alt/php84/usr/bin:$PATH

php -v                                    # confirm it changed
composer install --no-dev --optimize-autoloader

Any PHP from 8.3 upwards works — the requirement ^8.3 means "8.3 or newer, below 9.0", so 8.4 is equally supported. If the 8.3 binary on your host also fails, just use the highest 8.x available; that is a normal, supported setup, not a workaround.

Prefer the PATH export over prefixing a single command: npm run build shells out to php artisan internally, so a prefix-only fix clears this error and then breaks at the frontend build instead. The export lasts for the current SSH session only — re-run it whenever you reconnect, and spell the full binary path out in your cron entry, because cron does not read your shell profile.

A specific PHP binary still fails, even though its version looks right

Shared hosts compile each PHP version separately, and one of them can be missing an extension the others have. Check that binary against the required list:

/opt/alt/php84/usr/bin/php -m           # modules this binary has
/opt/alt/php84/usr/bin/php -v

The installer needs pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, json, curl, fileinfo and bcmath. If one is missing, either enable it for that version in your hosting panel's PHP extensions screen, or switch to a version that already has it. Composer prints exactly which requirement failed — read past the first line of the error, as it often lists a missing ext-… rather than the version itself.

"npm: command not found" on the server

Many shared hosts have Node installed but not on your PATH, and some do not ship it at all. Look for it the same way as PHP:

which node npm
ls /opt/alt/alt-nodejs*/root/usr/bin/npm 2>/dev/null    # CloudLinux / Hostinger layout
ls /usr/bin/node* /usr/local/bin/node* 2>/dev/null

If a recent version turns up (you need Node 20.19+), put it on your PATH alongside PHP and carry on:

export PATH=/opt/alt/alt-nodejs20/root/usr/bin:$PATH
node -v && npm -v
npm ci && npm run build

Some hosting panels also expose a "Node.js" or "Setup Node.js App" screen that enables it for your account — worth a look before giving up.

No Node on the server at all — build the frontend on your own computer

This is completely normal on shared hosting, and the result is byte-for-byte identical. On your own machine, in the same app folder you are about to upload:

composer install --no-dev --optimize-autoloader
cp .env.example .env
npm ci
npm run build          # creates public/build/

Then upload the generated public/build/ folder (and vendor/, if Composer would not run on the server either) into the same place on the host. Nothing else needs Node — it is only used to compile the assets.

The build needs PHP available locally, because it shells out to php artisan to generate route helpers. If your own machine has no PHP, use the host to run Composer and only build the assets elsewhere.

You only need to repeat this if you edit the frontend source. A plain upgrade of the app means uploading a fresh public/build/ along with the new code.

Composer suggests "please run composer update" — should you?

No. The message is generic Composer advice, but composer update resolves a brand-new dependency set that was never tested against this release, and can leave you with a subtly broken install. The lock file is correct; the problem is which PHP binary is running. Fix the binary and re-run composer install.

Home page works, every other URL is 404

Apache is not passing the request to Laravel. Confirm mod_rewrite is enabled and that public/.htaccess survived the upload — some FTP clients skip dot-files. On Nginx, the try_files $uri $uri/ /index.php?$query_string; line is missing.

Site loads but CSS/JS 404, page looks unstyled

The frontend was not built, or the document root points at the app folder instead of public/. Run npm ci && npm run build, then confirm the domain serves …/public.

"Mixed content" warnings, images blocked

APP_URL still starts with http:// while the site is served over HTTPS. Fix APP_URL, then php artisan config:clear.

Changes to code or .env do nothing

A cached config is being served. Run php artisan config:clear (and route:clear, view:clear). Remember to re-run config:cache afterwards in production.

Scheduled jobs never run, and nothing is logged

Nearly always the cron entry uses plain php. Cron does not read your shell profile, so it gets the system default — often an older PHP than your site needs — and with >> /dev/null 2>&1 the failure is discarded, so it looks like cron never fired at all. Spell out the full binary path (/opt/alt/php84/usr/bin/php, /usr/local/bin/php, …) and log somewhere real while you verify:

* * * * * cd /path/to/app && /opt/alt/php84/usr/bin/php artisan schedule:run >> storage/logs/cron.log 2>&1

Then run that exact command by hand — you should get a list of tasks or "No scheduled commands are ready to run". See Cron & Queue Workers.

Uploads fail or return 500

storage/ not writable, or the file exceeds PHP's limits. Raise upload_max_filesize and post_max_size (and client_max_body_size on Nginx).

Wizard says the database already contains tables

Something ran migrations before the wizard — usually composer run setup. Drop and recreate the empty database, delete storage/app/.sys if present, and reopen /install.

Need to re-run the installer

Drop the database, recreate it empty, delete storage/app/.sys, then open /install again.

Apps — build

"Execution failed for task ':app:processDebugGoogleServices'"

The package_name inside android/app/google-services.json does not equal your applicationId. Register the exact id in Firebase and download a fresh file — editing the id by hand inside the JSON also works but must match character for character.

App builds, then crashes instantly with ClassNotFoundException: MainActivity

You changed the package id but not the Kotlin folder path. android/app/src/main/kotlin/…/MainActivity.kt must sit in folders mirroring the new id, and its first line must be package your.new.id. See any app's Rebranding page.

"Unsupported class file major version" / Java version errors

Gradle is running on a JDK it does not support. Install JDK 17, then point Flutter at it: flutter config --jdk-dir=/path/to/jdk-17.

"SDK location not found"

android/local.properties is missing or has the wrong path. Open the android/ folder once in Android Studio and it writes the file, or create it with sdk.dir=/path/to/Android/sdk.

Gradle download hangs or fails

First build pulls the Gradle distribution and every dependency — slow connections time out. Retry; if it keeps failing, run flutter clean then flutter pub get before building again.

Release rejected by Play Store (debug signed)

Create your keystore and android/key.properties — see each app's "Build Android" page. A debug-signed AAB is always rejected.

Play: "package name already exists"

That application id is taken — either by your own earlier upload or someone else's app. Ids are global and permanent; pick a different one and rebuild.

Play: "Version code N has already been used"

Increase versionCode in android/version.properties (not local.properties, which Flutter regenerates) and rebuild.

iOS: CocoaPods errors on build

In the app's ios/ folder run pod repo update then pod install. If it still fails, delete Podfile.lock and Pods/ and run pod install again.

iOS: "Signing for Runner requires a development team"

Open ios/Runner.xcworkspace in Xcode, select the Runner target → Signing & Capabilities, and choose your Apple Developer team.

iOS: no Runner.xcodeproj

Recreate the iOS shell once inside the app folder: flutter create --platforms=ios --org com.yourcompany . then re-run the icon generator.

Apps — runtime

Map is blank / "For development purposes only"

Maps key missing, unrestricted-but-billing-off, or restricted to the wrong package/SHA. See Google Maps.

Google login fails

Add SHA-1/SHA-256 to Firebase and set the Web OAuth client id in Admin → Settings → Login Setting → Google. For Play installs, add the Play App Signing SHA too.

Facebook login fails

Add the Android key hash, set the iOS bundle id, and switch the Facebook app to Live. See Facebook App.

Push not received

App built with a non-matching/placeholder Firebase config, or the server service-account JSON isn't set. See FCM Push.

App can't reach the API

Wrong API base URL, or HTTPS/cleartext mismatch. On a real device use your LAN IP for a local server (10.0.2.2 is emulator-only). Check lib/config/env.dart.

Every request 404s after changing the URL

A trailing slash on the base URL produces a double slash such as https://site.com//api/v2/seller/login. Remove the trailing slash.

OTP never arrives

Check which gateway is active in Admin → SMS Gateway and that it has credit. During testing use the Firebase test numbers, or read the OTP from storage/logs/laravel.log.

Rider location not updating for customers

Background location permission was denied, or battery optimisation is killing the app. Grant "Allow all the time" on Android and disable battery optimisation for the partner app.

Payments & orders

Payment succeeds but the order stays unpaid

The gateway's webhook is not reaching your server. Register the webhook URL in the gateway dashboard, make sure it is publicly reachable over HTTPS, and check storage/logs/laravel.log for rejected callbacks. A local or password-protected site cannot receive webhooks.

Gateway hidden at checkout

Most gateways only support certain currencies. If your store currency is unsupported the method is hidden automatically — the Payment Methods screen flags the mismatch.

Gateway works in test, fails live

Test keys are still saved, or the account is not fully activated with the provider. Each gateway has separate test and live credentials.

Customer charged twice

Usually a retried webhook. Payments are matched by the gateway reference, so re-check the order's transaction list before refunding — a duplicate charge at the gateway must be refunded there.

Order placed but no seller notification

The queue worker is not running, or the seller's device has no valid token (never signed in, or signed out). See Push above.

FAQ

Can I sell with only the website (no apps)?

Yes — the storefront is fully functional on the web. Build and publish the apps whenever you're ready.

Where are my payment / SMS / API keys stored?

In your database, entered via the admin panel — not in source code. See Configuration Model.

Can I change currency, modules or branding later?

Yes, anytime from the admin panel. The apps pick up the changes at next launch — no rebuild needed.

Do I need my own Firebase / Maps accounts?

Yes. The product ships with placeholders; you must use your own keys (this protects your billing and is required by Google/Apple).

How do I update after editing code?

Backend: re-deploy, run composer install, npm run build, php artisan migrate --force (if applicable) and php artisan queue:restart. Apps: raise versionCode/versionName in android/version.properties and rebuild.

Where do I get support?

Through your CodeCanyon item's support channel / the author's support address listed on the item page.

🏠

Back to the documentation home.