Troubleshooting

The problems that come up most often, what they mean and how to fix them.

"TWERPLEX needs PHP 8.3 or newer"

The server runs an older PHP. Select PHP 8.3 or newer for the site in your hosting panel (cPanel: MultiPHP Manager; Plesk: PHP Settings) and make sure the cron job uses the same version.

"Your web server needs one more step"

The server ignores .htaccess files, so the package root is being served directly. On Apache enable AllowOverride All for the folder; on nginx use the server block from Installation or point the document root at public/.

Every page except the front page is a 404

mod_rewrite is off or .htaccess files are ignored. Enable the module and AllowOverride, or on nginx check the try_files line.

A blank page or a 500 error

• Check that storage/ and bootstrap/cache/ are writable.
• Read the end of storage/logs/laravel.log; the message there names the cause.
• If it happened right after an update, see Updating for the recovery script.
• If it happened after installing an extension, create storage/app/extensions.safe to load the site without extensions.

Styles or icons are missing

The public/build/ folder was not uploaded completely, or the site is reached through a different address than APP_URL. Re-upload the folder and check the address.

The site moved to another domain or folder

Edit APP_URL in .env, then run:

php artisan optimize:clear
php artisan optimize

Links, the trusted host, the session cookie and the storefront address all follow APP_URL. Without shell access, delete bootstrap/cache/config.php with your file manager after changing the value; the application then reads .env directly until the caches are rebuilt. Re-check the licence under System → Licence afterwards.

Nothing happens on a schedule

Invoices are not generated, emails stay queued, provisioning waits: the cron job is not running. Command → Overview shows when the scheduler last ran. Check the cron line, the path to PHP and the PHP version used by cron (see Cron and queue). Operations → Recovery lists overdue tasks and queued jobs.

Emails are not delivered

Send a test message from System → Settings → Email and read the server's answer. A mailer set to log writes messages to the log file instead of sending them. Check SPF and DKIM for the sender domain if messages arrive in spam.

A payment was made but the invoice is unpaid

Check the gateway's own webhook log: if the notification was never sent or was answered with an error, compare the notification address shown on the connection page (Developers → Integrations) and the signing secret or webhook ID with what the gateway has. A rejected notification leaves its reason in storage/logs/laravel.log. Commerce → Reconciliation finds payments the gateway knows and the ledger does not, and lets you record them.

Locked out of the staff area

• Lost authenticator: php artisan staff:reset-two-factor you@example.com, then set it up again after signing in.
• Your address is not in the IP allowlist: php artisan staff:clear-ip-allowlist.
• Forgotten password: use the password reset link on the sign-in page; it needs working email.

A failed update

System → Updates shows the step that failed and the reason, and the previous version is already back in place. If the application does not start at all, run php storage/framework/update-recovery.php status and, if needed, rollback.

Reporting a problem

Include the version (System → Updates), the PHP version, the web server, the database engine, what you did, what you expected and the relevant lines from storage/logs/laravel.log. Remove passwords and keys from anything you send.