Troubleshooting Guide

Quick Reference

#	Error	Jump to
1	Blank white page after install	Error 1
2	500 Internal Server Error	Error 2
3	Database connection failed	Error 3
4	404 on all pages except homepage	Error 4
5	Installer hangs or won’t finish	Error 5
6	Images not loading after install	Error 6
7	Emails not sending	Error 7
8	Surf bar not awarding credits	Error 8
9	License activation fails	Error 9
10	Can’t log into admin panel	Error 10

---

Error 1: Blank White Page After Install

Symptom: You visit your domain and see a completely blank white page — no error message, no content, nothing at all.

Cause: The two most common causes are (a) the document root is pointing at the script root instead of the public/ subfolder, or (b) PHP error display is turned off and the page is failing silently due to a misconfiguration.

Fix (step by step):

1. Check your document root. In cPanel, go to Domains and confirm the Document Root for your domain ends in /public — for example /home/youraccount/traffic-exchange/public. If it points to the script root (without /public), correct it and reload.

In DirectAdmin, go to Domain Setup, select your domain, and confirm the public directory path ends in /public.

1. Confirm PHP version. Go to MultiPHP Manager (cPanel) or PHP Version Selector (DirectAdmin) and confirm you are running PHP 8.3 or higher. The script will not run on older versions.

2. Check folder permissions. The storage/ and bootstrap/cache/ folders must be writable by the web server.

3. In cPanel File Manager, right-click each folder and set permissions to 755. If the blank page persists, try 775.

4. In DirectAdmin File Manager, the same permissions apply.

5. Check the error log. In cPanel, go to the Errors section (or open storage/logs/laravel.log via File Manager). The actual error message will be there. Common causes: a missing PHP extension, a wrong path in .env, or a permissions problem on a specific file.

6. Confirm .env exists. Navigate to your script root in File Manager. You should see a file named .env (not .env.example). The installer creates this file during setup. If it is missing, re-run the installer at yourdomain.com/install.

Prevention: Always point your domain’s document root at the public/ subfolder, not the script root. Verify PHP 8.3 is selected before uploading files.

---

Error 2: 500 Internal Server Error

Symptom: Your browser shows “500 Internal Server Error” or “An error occurred on the server” when you visit your site.

Cause: A 500 error typically means one of: a .htaccess conflict, the mod_rewrite Apache module is not enabled on the server, or a PHP fatal error (syntax error, missing extension, or memory limit exceeded).

Fix (step by step):

1. Check storage/logs/laravel.log. Open this file in cPanel or DirectAdmin File Manager and scroll to the bottom. The fatal error will be logged there with a file path and line number.

2. Verify .htaccess is in place. The script ships with a public/.htaccess file that handles URL routing. In cPanel File Manager, navigate to public/ and confirm .htaccess is present. If it is missing, re-download the script package and copy the file from public/.htaccess.

Note: File Manager hides dotfiles by default. In cPanel, click Settings (top right of File Manager) and tick Show Hidden Files to see .htaccess.

1. Check that mod_rewrite is available. On shared hosting, mod_rewrite is almost always enabled. If your host has disabled it, contact their support and ask them to enable mod_rewrite for your account.

2. Check PHP memory limit. In cPanel, go to MultiPHP INI Editor, select your PHP version, and confirm memory_limit is at least 128M. If it is lower, increase it.

3. Check for a conflicting .htaccess at the server root. If you uploaded any custom .htaccess to the script root (one level above public/), it may be interfering. The script root should not have an .htaccess file — only public/.htaccess should exist.

Prevention: Do not place custom .htaccess files in the script root. Confirm your host supports mod_rewrite before purchase.

---

Error 3: Database Connection Failed

Symptom: During installation or after, you see “Database connection failed”, “Could not connect to database”, or SQLSTATE[HY000] [2002] Connection refused.

Cause: The database credentials in .env are wrong, the database user has not been granted privileges, or the database host is incorrect.

Fix (step by step):

1. Open .env in cPanel or DirectAdmin File Manager (enable “Show Hidden Files” first). Locate the database block:

DB_HOST=127.0.0.1 DB_DATABASE=your_database_name DB_USERNAME=your_database_username DB_PASSWORD=your_password

1. Verify the database name and username. On cPanel, database names and usernames are prefixed with your cPanel account name (e.g. cpanelusername_dbname). The prefix is added automatically — your .env must use the full prefixed name.

On DirectAdmin, prefixes may differ. Go to MySQL Management in DirectAdmin to see the exact names of your databases and users.

1. Check the database host. On shared hosting, DB_HOST should almost always be 127.0.0.1 or localhost. Ask your host if you are unsure.

2. Verify user privileges. In cPanel, go to MySQL Databases, scroll to Current Databases, and confirm your user is listed under the database with All Privileges. If not, use the Add User To Database form to grant them.

In DirectAdmin, go to MySQL Management, click your database, and confirm the user is assigned with full privileges.

1. Test the connection manually. If your host provides phpMyAdmin (available in cPanel), log in using the database username and password. If you cannot log in, the credentials are wrong.

Prevention: Copy database credentials exactly as they appear in cPanel/DirectAdmin, including any account prefix.

---

Error 4: 404 on All Pages Except Homepage

Symptom: The homepage loads normally, but every other page — /login, /admin, /surf — returns a 404 Not Found error.

Cause: Apache’s mod_rewrite rules in public/.htaccess are not being applied. Either the .htaccess file is missing, AllowOverride is set to None on the server, or the rewrite engine is not enabled.

Fix (step by step):

1. Confirm .htaccess is present in public/. In cPanel or DirectAdmin File Manager, navigate to public/ and enable Show Hidden Files. You should see .htaccess. If it is missing, re-upload it from the script package.

2. Confirm the rewrite rules are intact. Open public/.htaccess and verify it contains: RewriteEngine On and RewriteRule ^ index.php [L] If the file is empty or truncated, replace it with the original from the script package.

3. Ask your host to enable AllowOverride All. Some server configurations set AllowOverride None, which means .htaccess files are completely ignored. Contact your host’s support and ask them to enable AllowOverride All for your domain’s directory.

4. DirectAdmin-specific: Some DirectAdmin setups require you to enable mod_rewrite explicitly. In DirectAdmin, go to Your Account → Site Summary/Usage/Details and confirm Apache rewrite rules are active. Contact your host if unsure.

Prevention: Test that a non-homepage URL works immediately after installation before configuring anything else. This confirms mod_rewrite is working.

---

Error 5: Installer Hangs / Won’t Finish

Symptom: The installer gets stuck mid-way — usually on the database migration step or the environment setup step — and does not progress. The browser may show a spinning loader indefinitely, a gateway timeout (504), or a blank page.

Cause: PHP’s max_execution_time is set too low for the migration step to complete, or a database timeout is interrupting the import.

Fix (step by step):

1. Increase PHP execution time. In cPanel, go to MultiPHP INI Editor, select your PHP version, and set max_execution_time to 120 (or higher). Save.

In DirectAdmin, go to PHP Version Selector → PHP Settings and increase max_execution_time.

1. Retry the installer. Visit yourdomain.com/install again. The installer is stateless — it is safe to retry. If you already passed the database configuration step, you may need to re-enter your credentials.

2. Check for a database import timeout. If the timeout persists after increasing execution time, check storage/logs/laravel.log for a specific SQL error. A common cause is the database user lacking CREATE or ALTER privileges.

3. Check your host’s PHP time limit. Some shared hosts impose a server-level max_execution_time cap (typically 30 seconds) that cannot be overridden via INI Editor. If you cannot increase the time limit, contact your host’s support and ask them to raise it temporarily, or consider a VPS plan where you control PHP settings directly.

4. Do not close the browser tab. If the migration step is running, closing the tab will interrupt it. Keep the tab open and wait at least 2–3 minutes before assuming it has failed.

Prevention: Verify with your host that max_execution_time can be set to 120 seconds before running the installer. VPS hosting avoids this limitation entirely.

---

Error 6: Images Not Loading After Install

Symptom: The site loads, but images — logos, avatars, ad images — appear as broken image icons. Sometimes the site appears styled correctly but all uploaded or script-generated images are missing.

Cause: The APP_URL in .env does not match the actual URL you are accessing the site on, causing image paths to point to the wrong domain or protocol. Mixed content (HTTP vs HTTPS) is a common variant of this.

Fix (step by step):

1. Check APP_URL in .env. Open your .env file and locate: APP_URL=https://yourdomain.com This must exactly match the URL you use to access the site — including https:// (not http://), no trailing slash, and the correct domain spelling.

2. Fix mixed content (HTTP/HTTPS mismatch). If your browser shows a padlock with a warning, open the browser console (F12 → Console tab). You will likely see errors about mixed content — images being loaded over HTTP while the page is HTTPS. This means APP_URL was set to http:// during install but your site now uses SSL.

Update .env: APP_URL=https://yourdomain.com Then clear the application cache. In cPanel Terminal (if available) run: php artisan config:clear && php artisan cache:clear If you do not have terminal access, contact support.

1. Confirm your SSL certificate is active. In cPanel, go to SSL/TLS Status and confirm your domain shows a green padlock. If SSL is not issued, the browser may refuse to load HTTPS images.

2. Check storage/ permissions. Uploaded images are stored in storage/app/public/. Ensure this directory is writable (permissions 755 or 775).

3. Confirm the storage symlink exists. The installer should create a symlink from public/storage to storage/app/public. If images stored by users are not loading, this symlink may be missing. Contact support if you cannot verify this via File Manager.

Prevention: Set APP_URL to your final HTTPS domain during the installer, and ensure SSL is active before running it.

---

Error 7: Emails Not Sending

Symptom: Members do not receive welcome emails, password reset emails, or newsletter broadcasts. No delivery error appears on screen, but emails simply do not arrive.

Cause: The default mail driver (MAIL_MAILER=log) writes emails to the log file instead of sending them. For real email delivery, you must configure SMTP credentials in .env. On many shared hosts, PHP’s mail() function is also disabled or unreliable.

Fix (step by step):

1. Check your current mail driver. Open .env and find: MAIL_MAILER=log If the value is log, emails are being written to storage/logs/laravel.log and not sent. This is the default development setting.

2. Configure SMTP. Update these values in .env with your SMTP provider credentials (Mailgun, Brevo, SendGrid, Gmail SMTP, or your host’s SMTP):

MAIL_MAILER=smtp MAIL_HOST=smtp.your-provider.com MAIL_PORT=587 MAIL_USERNAME=your@email.com MAIL_PASSWORD=your-smtp-password MAIL_FROM_ADDRESS="noreply@yourdomain.com" MAIL_FROM_NAME="Your TE Name" MAIL_SCHEME=null

Common port values: 587 for TLS (most providers), 465 for SSL, 25 for unencrypted (not recommended).

1. Clear the config cache. After editing .env, the config must be refreshed. If you have terminal access: php artisan config:clear Without terminal access, you can temporarily rename .env and rename it back — this forces Laravel to re-read the file on next request, though clearing the cache properly is preferred.

2. Check your host’s SMTP restrictions. Many shared hosts block outbound SMTP on port 25. Use port 587 (TLS) instead. Some hosts completely block external SMTP — in this case, use a transactional email API service (Mailgun, Brevo, etc.) which connect over HTTPS, not raw SMTP.

3. Check spam/junk folder. Test emails from a fresh configuration often land in spam. Add your sending domain to SPF and DKIM records to improve deliverability. Your SMTP provider’s documentation will have the exact DNS records to add.

Prevention: Configure SMTP credentials before launching your TE. Never leave MAIL_MAILER=log in production.

---

Error 8: Surf Bar Not Awarding Credits

Symptom: Members surf ads but their credit balance does not increase. The timer counts down to zero, but nothing happens — no credit is awarded and no next site loads.

Cause: The scheduler cron job is not running, which means the background tasks that process credit awards are not executing. The surf credit system relies on scheduled jobs that run every minute.

Fix (step by step):

1. Verify the cron job is set up. In cPanel, go to Cron Jobs and look for an entry containing php artisan schedule:run. If no such entry exists, the cron job was never set up.

2. Add the cron job. In cPanel Cron Jobs, add a new entry set to run every minute:

* * * * * cd /home/youraccount/traffic-exchange && php artisan schedule:run >> /dev/null 2>&1

Replace /home/youraccount/traffic-exchange with the actual path to your script root (not the public/ folder).

In DirectAdmin, go to Cron Jobs and add the same command with the same every-minute schedule.

1. Find the correct PHP binary path. Some hosts require you to use the full path to the PHP binary instead of just php. Common paths are:
2. /usr/bin/php
3. /usr/local/bin/php
4. /opt/alt/php83/usr/bin/php

In cPanel Terminal (if available), run which php to find the correct path. If in doubt, contact your host’s support and ask for the full path to PHP 8.3.

Updated cron command with full path example: * * * * * cd /home/youraccount/traffic-exchange && /usr/local/bin/php artisan schedule:run >> /dev/null 2>&1

1. Wait one minute and retest. Cron jobs run on a schedule. After adding the cron entry, wait at least one full minute before testing surf credit awards again.

2. Check the scheduler log. Run a manual test by pasting the cron command into cPanel’s Terminal. If you see errors about file paths or PHP, fix the command. Check storage/logs/laravel.log for any scheduler-related errors.

Prevention: Set up the cron job immediately after installation as described in the installation guide, before going live.

---

Error 9: License Activation Fails

Symptom: During the installer’s license step, or when using the admin panel’s license section, you see “License activation failed”, “Invalid license key”, or “License already active on another domain”.

Cause: The license key was entered incorrectly, the domain being activated does not match the purchase, there is an instance ID conflict from a previous install, or your license has expired.

Fix (step by step):

1. Check for copy-paste errors. Go to your purchase confirmation email from trafficexchangescript.com and copy the license key directly. Paste it without any leading or trailing spaces. License keys are case-sensitive.

2. Confirm your domain matches your purchase. Your license is tied to the domain you registered it against at purchase. If you are installing on a different domain (e.g. you bought for mysite.com but are now installing on te.mysite.com), contact support to update the domain on your license.

3. Check for a duplicate activation. If you have previously installed on this same domain and are reinstalling, the license server may see this as a second activation. Contact support at support@trafficexchangescript.com to reset your activation count.

4. Verify outbound HTTPS is allowed. The license check makes an outbound HTTPS call to trafficexchangescript.com. On shared hosting this works by default. If it fails, ask your host whether outbound HTTPS (port 443) is allowed.

5. Check .env for license values. After a successful install, you can see the stored values in .env: TE_LICENSE_KEY=your-license-key TE_LICENSE_PRODUCT_ID=21 TE_LICENSE_API_URL=https://trafficexchangescript.com/wp-json/wlm/v1 If these values are wrong or missing, edit .env to correct them and then clear the config cache (php artisan config:clear in terminal).

6. Contact support if the key shows as expired. License expiry, refunds, or account issues are handled by the trafficexchangescript.com billing team. Email support@trafficexchangescript.com with your purchase email address and order number.

Prevention: Copy your license key from the purchase email rather than re-typing it. Keep your purchase confirmation email for reference.

---

Error 10: Can’t Log Into Admin Panel

Symptom: Visiting yourdomain.com/admin shows a 404 error, or you reach a login form but your credentials are rejected.

Cause: Either the admin path has been changed in .env (so /admin is no longer the correct URL), or the admin account credentials do not match what was set during installation.

Fix (step by step):

If you see a 404 at /admin:

1. Check TE_ADMIN_PATH in .env. Open .env and look for: TE_ADMIN_PATH=admin If this value is set to something other than admin — for example dashboard or control — your admin URL is yourdomain.com/dashboard instead. Visit that URL.

If TE_ADMIN_PATH is not in your .env, the default admin should work. Check that mod_rewrite is working (see Error 4) and that the homepage loads before concluding the admin path is wrong.

If you reach the login form but credentials are rejected:

1. Confirm you are using the correct credentials. The admin username and password are the ones you set during the installer’s Site Configuration step (Step 3 of 7). These are separate from your cPanel login.

2. Reset the admin password via the database. If you cannot remember your admin password, you can reset it using phpMyAdmin:

3. In cPanel, open phpMyAdmin and select your database.
4. Open the users table and find your admin account (look for the user with role = admin or similar).
5. Click Edit on that row.
6. In the password column, select the Function dropdown and choose MD5. Then enter your new password in the Value field.

Note: The exact table name and column structure depend on the script version. Check storage/logs/laravel.log if the above steps do not match what you see.

1. Use the password reset form. If your site’s email is configured (see Error 7), visit yourdomain.com/password/reset and use your admin email to receive a reset link.

2. Check for a session or cookie conflict. If you previously logged in on a different domain or a test install, your browser may be holding a stale session cookie. Try opening an Incognito/Private browsing window and logging in from there.

Prevention: Record your admin credentials immediately after installation. Store them in a password manager.

---

Still Stuck?

If none of the steps above resolve your issue:

1. Read storage/logs/laravel.log. Open this file in File Manager and look at the most recent error entry. Copy the error message and stack trace.

2. Email support at support@trafficexchangescript.com. Include:

3. Your domain URL
4. The exact error message you see (screenshot or text)
5. The relevant lines from storage/logs/laravel.log
6. Your hosting environment (cPanel/DirectAdmin, host name, PHP version)
7. What you have already tried

The more detail you provide, the faster we can help.

---

— The Traffic Exchange Script Support Team

Screenshots